Draft a response with AI

Overview

Have AI write a reply to a review, in a tone you choose. The draft is saved but not posted.

Use this to give a business owner a starting point, or to respond at scale. Review the draft, edit it if you like, then post it with Post or edit a response.

You'll need the store_id and review_id. Optional: a tone (professional, casual, empathetic, apologetic, grateful, neutral), a short style hint, and instructions such as "mention our support team". The review's text and rating are read automatically.

Returns the draft text and its ai_review_response_id, plus how many AI drafts you have left this period. Each draft counts against your plan's AI allowance: on a hard-stop plan you get a 403 once it's used up; on an overage plan the draft is billed at your overage rate.

Prerequisites

A bearer token. See Authentication.
The location's id (store_id) and the id of one of its reviews (review_id).
AI responses must be on the location's plan.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/account/generate-ai-response

Authentication

Partner or Account token

store_id and review_id must be inside your own account tree, and the review must belong to that location. A Partner token can draft for any location under the partner; an Account token only for its own locations.
A location or review outside your tree is rejected with 422.

Rate limit

60 requests per minute, counted per user (the token’s user). See Rate limits.

Request parameters

None.

Request body

Field	Type	Required	Description
`store_id`	integer	Yes	The location the review belongs to. Must exist and be inside your account tree.
`review_id`	integer	Yes	The review to draft a reply for. Must exist, be inside your account tree and belong to `store_id`.
`tone`	string	No	`professional`, `casual`, `empathetic`, `apologetic`, `grateful` or `neutral`. Defaults to `professional`.
`style`	string	No	A short style hint, e.g. `Short and friendly`. At most 500 characters.
`owner_instructions`	string	No	Instructions for the draft, e.g. `Mention our support team`. At most 1,000 characters.

The review's text and rating are read from the review; you don't send them.

Request payload

{
  "store_id": 3007,
  "review_id": 279309,
  "tone": "professional",
  "style": "Short and friendly",
  "owner_instructions": "Mention our support team"
}

Response body

The payload is inside data.

Field	Type	Description
`success`	boolean	`true`.
`data.response_text`	string	The draft reply.
`data.ai_review_response_id`	integer	The draft's id. Send it as `ai_response_id` when you post the reply with Post or edit a response.
`data.remaining`	integer or null	AI drafts left on the location's allowance this period. `null` when there's no cap.
`data.overage`	boolean	`true` when this draft was billed as overage.

The response also carries the allowance in headers: X-Feature (ai_response), X-Feature-Limit, X-Feature-Used, X-Feature-Remaining (unlimited when there's no cap) and X-Feature-Hard-Stop (1 or 0).

Response payload

{
  "data": {
    "success": true,
    "data": {
      "response_text": "Thank you for your positive rating. We appreciate your support and are glad to know you had a good experience with us.\n\nIf there's anything we can do to make your next visit even better, please don't hesitate to reach out. We look forward to serving you again soon.",
      "ai_review_response_id": 39,
      "remaining": 47,
      "overage": false
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

403 AI allowance used up

{
  "message": "Limit reached for 'AI Responses': 50 of 50 units consumed this period.",
  "status": "error",
  "errors": {
    "remaining": 0
  }
}

403 AI responses not on the plan

{
  "message": "Feature 'AI Responses' is not enabled on this plan.",
  "status": "error",
  "errors": {
    "remaining": null
  }
}

422 Review from another location

{
  "message": "The selected review does not belong to the given store.",
  "errors": {
    "review_id": [
      "The selected review does not belong to the given store."
    ]
  }
}

422 Location and review outside your tree

{
  "message": "The selected store id does not belong to your company hierarchy. (and 1 more error)",
  "errors": {
    "store_id": [
      "The selected store id does not belong to your company hierarchy."
    ],
    "review_id": [
      "The selected review id does not belong to your company hierarchy."
    ]
  }
}

422 Invalid tone

{
  "message": "The selected tone is invalid.",
  "errors": {
    "tone": [
      "The selected tone is invalid."
    ]
  }
}

502 AI provider error

{
  "message": "AI response provider returned an error.",
  "status": "error",
  "errors": {
    "reference": {
      "rd_request_id": null,
      "rd_error_code": null
    }
  }
}

504 AI provider unreachable

{
  "message": "AI response provider is currently unreachable.",
  "status": "error",
  "errors": {
    "reference": {
      "rd_request_id": null,
      "rd_error_code": null
    }
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Status	Meaning
`200`	The draft is saved and returned.
`401`	The token is missing, expired or invalid.
`403`	The AI allowance is used up on a hard-stop plan, AI responses aren't on the location's plan, or the location has no active plan.
`404`	The location's partner couldn't be found.
`422`	A field is missing or invalid, the location or review is outside your tree, or the review belongs to another location.
`429`	The AI provider is rate-limiting requests. Try again later.
`500`	Unexpected server error.
`502`	The AI provider returned an error or rejected the request.
`504`	The AI provider is unreachable or timed out.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/generate-ai-response" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 3007, "review_id": 279309, "tone": "professional", "style": "Short and friendly", "owner_instructions": "Mention our support team"}'