Complaints

People can file a complaint in the Scout messenger. They pick one of your categories, answer that category's questions and say what happened. Your team handles it under Engage → Complaints, and webhooks send it to your own systems or a Slack channel.

Turning it on

1. The messenger must be on (Scout → Live in your app).
2. Open Complaints → Categories and add the categories people can pick, for example Billing & charges or Something isn't working. For each one you set:
   • a hint shown under the name,
   • a key used in webhook payloads (billing),
   • an optional teammate new complaints are assigned to,
   • up to 8 extra questions, short text or a choice, each optional or required (an order number, "What would put this right?").
3. Turn on Let people file complaints in the messenger.

Two more switches on the same tab:

• Let Scout offer the form. When someone sounds unhappy, Scout helps first, then offers a "File a complaint" button with the best matching category picked and the person's last messages filled in. It offers it at most once per conversation.
• Allow visitors who aren't signed in. Off by default. When on, visitors your app hasn't identified (identify()) can file too, but must give an email address so you can reply. The address isn't verified.

Categories are shown in the order of the list. Archive a category to stop offering it: complaints already filed in it keep it. A category nobody has filed in can be deleted.

What people see

• Home: a "File a complaint" card, and "Your complaint" with its status once they've filed one.
• The form: the category, its questions, "What happened?" and an optional screenshot. Images are scaled down in the browser and sent with the complaint (PNG, JPEG, WebP or GIF, up to 2 MB). The page they're on is attached.
• Filed: a reference such as CMP-1042 and its progress: Received → In review → Resolved.

Every complaint belongs to a conversation: the Scout chat it was filed from, or one started for it. That conversation goes to your team (Scout stops answering in it), your replies show in the messenger, and the person sees a note when the status changes.

From your own app, open the form with:

guidely.openComplaint();                 // starts with the category list
guidely.openComplaint("<category id>");  // with a category picked

The ids are in the code sample at the bottom of the Categories tab. openComplaint does nothing when complaints are off or there are no categories.

Handling complaints

Complaints → All complaints lists them with filters for status, category and assignee, and search by reference, text, email or user id. The numbers at the top: open and in review, filed in the last 7 days, the median time to your team's first reply (last 30 days) and resolved in the last 30 days. The sidebar badge counts new complaints nobody has picked up.

A complaint's page shows what they said, the answers to the category's questions and any screenshot, and its activity: filing, status, assignee and category changes, replies, internal notes and every webhook delivery. On the side: who filed it (claimed by your app's SDK, so unverified), their earlier complaints, the page and browser, a link to the conversation in the Inbox and the recordings from before they filed.

• Reply sends a message to the person in the messenger. Replying to an open complaint moves it to In review and assigns it to you if nobody had it. Send and resolve does both.
• Internal note is only for your team.
• Status, assignee and category can be changed at any time. Assignees need Reply in the Inbox.

Viewers can read complaints. Replying and changing them needs Reply in the Inbox; categories, the switches and webhooks need Manage Scout.

Webhooks

Complaints → Webhooks sends complaint events to a URL or a Slack channel. Each webhook has:

Resolving fires both changes status and is resolved, so a webhook listening to both gets two deliveries. Deleting a category takes it out of webhooks limited to it; a webhook left with no categories is turned off rather than starting to fire for every category.

URL webhooks

A POST with JSON, signed like flag webhooks: X-Guidely-Signature: sha256=<hex> is the HMAC-SHA256 of the raw body with the webhook's signing secret (shown once when you create it or make a new one), and X-Guidely-Event carries the type.

{
  "type": "complaint.filed",
  "projectId": "…",
  "environment": "production",
  "at": "2026-10-24T14:32:08.000Z",
  "complaint": {
    "id": "…",
    "reference": "CMP-1042",
    "url": "https://app.guidely…/app/<project>/complaints/<id>",
    "status": "open",
    "category": { "id": "…", "key": "billing", "name": "Billing & charges" },
    "description": "I was charged twice for my October plan…",
    "answers": [{ "id": "invoice_or_order_number", "label": "Invoice or order number", "value": "INV-20431" }],
    "page": "/settings/billing",
    "attachments": 1,
    "assignee": null,
    "createdAt": "…",
    "resolvedAt": null
  },
  "person": { "userId": "user_42", "anonymousId": "…", "name": "Priya Shah", "email": "priya@example.com" },
  "conversationId": "…",
  "actor": null
}

Status events add change: { from, to } and the teammate in actor; reply events add reply: { body }. Screenshots are never sent: open the complaint to see them. The payload is built when the event happens, so retries send the complaint as it was then.

Slack

Pick a Slack integration (an incoming webhook, added under Integrations). The channel gets a message with the reference and category, what they wrote (or your reply), the person, page, answers and assignee, and an Open complaint button. Everything the person typed is escaped.

Delivery

Deliveries are sent in the background shortly after the change. A failure (no answer in 10 s, or a status outside 2xx) is retried after 30 s, 1, 2 and 4 minutes; after 5 attempts it is marked failed and Send again on the webhook's delivery log starts over. Send test event sends an example right away. Delivery logs are kept for 30 days.

Limits

Data handling

Complaints hold what the person wrote, their answers and screenshot, the page URL, browser user agent and IP address, and the identity and traits your app's SDK sent. Screenshots are stored privately and only served to signed-in teammates. Resolved complaints are deleted with the project's event retention, and Delete user removes that person's complaints too. Webhooks send the payload above to the URL you set; Scout sees the category names and hints when it may offer the form.