Set up review prompts and Discord announcements

Two small tools let you talk to your customers where they already are. The review prompt asks a customer to leave a review on your Trustpilot page. An announcement is a message your team posts to a Discord channel through a webhook.

Your team manages both in the staff console, under Marketing. The owner and scripts use the API, which this page describes.

• You need the Admin or Owner role in the organization. Billing, support and read-only members cannot read or change these settings.
• For reviews, you need your Trustpilot review link. It starts with https:// and is on trustpilot.com.
• For announcements, you need a Discord webhook. In Discord, open the channel's settings, then Integrations, then Webhooks, make a webhook and copy its address. It starts with https://discord.com/api/webhooks/.

Owners and admins use the page in the dashboard. Your team can do the same in the staff console, as Marketing audience in the staff console describes. A member with another role does not see the page, and its address opens Overview.

1. In the dashboard, open the organization, then Settings, then Reviews and announcements.
2. Under Reviews, turn on Ask customers for a review, paste your "Trustpilot review link" and set "Days old an account is before we ask" and "Days we stay quiet after a customer closes the prompt". Select Save changes. The page says "The review prompt turned on." when the switch was the only change, and "Review settings saved." otherwise. A link the API refuses, or a switch turned on with no link, shows its sentence under "Trustpilot review link".
3. Read Review invitation email on the same card. It says whether the invitation flow is on and counts its emails as Scheduled, Sent, Skipped and Failed, with Last sent. Turn the flow on or off in Email flows, which the card links to.
4. Under Discord webhook, paste the "Discord webhook address", add a "Channel name" if you like, and select Save changes. The card then shows Saved with the last four characters of the webhook's ID, and never the address. Replace opens the field for a new address. Remove is staged until you select Save changes, and Keep it undoes it. The channel name is for your team and is not sent to Discord.
5. Under Post an announcement, fill in "Title" (optional), "Message" and "Link" (optional). The page counts the message against 1,800 characters. Select Post announcement…, check the text and the channel in the question, and select Post announcement.

When it works, the page says "Announcement posted." and the post appears under Announcements posted with the channel, who posted it and when. The list holds the last 20 posts, and a post that Discord did not take shows as Failed with its reason.

Posting needs a saved webhook, so the button stays off until you save one. You can post 10 an hour, and the page shows the API's sentence and how long to wait when you pass that. When Discord does not take a message, the card says Discord did not take the message and gives the reason in a sentence, and nothing was posted.

The review prompt asks a signed-in customer on your storefront to leave a review. It waits until the customer's account is old enough, and after a customer closes it, it stays quiet for a while in that browser. It shows only while it is on and has a link.

GET /reviews reads the settings and PUT /reviews changes them. Send only what changes.

curl -X PUT "https://api.coritan.com/api/v1/orgs/acme/reviews" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "review_url": "https://www.trustpilot.com/evaluate/example.com", "min_account_age_days": 7}'

{
  "enabled": true,
  "review_url": "https://www.trustpilot.com/evaluate/example.com",
  "min_account_age_days": 7,
  "dismiss_days": 30,
  "invitations": {
    "enabled": false, "scheduled": 0, "sent": 0, "skipped": 0, "failed": 0, "last_sent_at": null
  },
  "changed": ["enabled", "review_url", "min_account_age_days"]
}

changed lists the settings that differ from before. Saving what is already saved changes nothing and writes no audit entry. A value that does not fit answers 422 with detail, the sentence to show, and field, the setting it belongs to. The storefront applies a change to new page loads within a minute.

The review invitation is an email to a customer some time after their first paid order, sent by one of your email flows. It uses the same review link, and it is sent only while enabled is on and the link is set. invitations in the answer shows how it is doing:

enabled

Whether the review invitation flow is switched on.

scheduled, sent, skipped and failed

How many invitation emails are in each state. All four are 0 until the flow has run.

last_sent_at

When an invitation email last went out, or null.

Save your Discord webhook once. Your team can then post a message to its channel from the staff console, and a script can post through the API.

PUT /announcements saves the webhook:

The webhook address is a secret. We seal it, never show it again, and never write it to the audit log. GET /announcements answers {configured, channel_label, webhook_hint}. webhook_hint is the last four characters of the webhook's ID, so you can tell which webhook is saved:

{ "configured": true, "channel_label": "#announcements", "webhook_hint": "3456" }

An address that is not a Discord webhook answers 422 with field webhook_url. To replace the webhook, save a new address. Removing it stops announcements until you save another.

POST /announcements/post sends one message to the saved webhook.

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/announcements/post" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Servers are back", "content": "The maintenance is over. Thank you for waiting.", "link": "https://status.example.com"}'

The title, the text and the link make one message, and together they must fit Discord's 2,000 characters, or the answer is 422. Nothing in the message can mention a role or a person: @everyone and @here show as plain text and ping nobody.

A post answers one of these:

200 with {"posted": true}

Discord took the message.

409

No webhook is saved. Save one first.

422

The message does not fit. field names the part to change.

429

The organization has posted 10 messages in the last hour. Wait and try again. The limit counts every attempt for the organization, whoever posts.

502

Discord did not take the message, and detail says why in a sentence, such as that the webhook no longer works. Nothing was posted. We never show what Discord answered.

GET /announcements/history lists the announcements newest first. It takes limit, 1 to 100 and 20 by default. Each entry has status (posted or failed), the title, content and link that were sent, the channel_label saved then, error (why a failed post failed), actor_type (staff, user or admin for Coritan staff), actor ({id, name} or null) and created_at.

For reviews, the answer shows your settings and changed names what you changed. For announcements, a post answers {"posted": true} and the message appears in your Discord channel. Every change and every post is in the audit log:

422 with field review_url

The link must start with https:// and be on trustpilot.com. A link on another site is refused. The prompt also cannot be on without a link, and a link cannot be removed while it is on.

422 with field webhook_url

Copy the webhook address again from Discord. It starts with https://discord.com/api/webhooks/, then a number and a token.

502 and the sentence says the webhook no longer works

The webhook was deleted in Discord, or its channel was. Make a new webhook and save its address.

429 on a post

Ten posts an hour is the limit for the organization. The history shows what was already posted.

The prompt does not appear

It needs enabled and a link. A customer sees it only after their account is min_account_age_days old, and not for dismiss_days after they close it.

The staff console's routes under /api/v1/orgs/{org_slug}/staff/marketing/reviews and /api/v1/orgs/{org_slug}/staff/marketing/announcements answer the same, for the Admin and Owner roles, and platform staff have the same routes for any organization in the admin console. All of them need an access token, sent as Authorization: Bearer $CORITAN_TOKEN.

• Read the organization audit log
• How customers and orders are attributed
• Connect a Discord server

• Make campaign links to announce a launch with a link you can measure.
• Connect a Discord server to link your community's server to your organization.