---
title: "Create Feedback Request"
method: POST
path: "/api/v1/feedback/request"
tags: ["feedback"]
---

# Create Feedback Request

`POST /api/v1/feedback/request`

## Request

- Base URL: `https://www.elocuenti.com`
- URL: `https://www.elocuenti.com/api/v1/feedback/request`
- Auth: HTTP bearer

Send a WhatsApp feedback template for an order and enroll the conversation
into the tenant's feedback pipeline so the AI collects rating + comment.

## Request body

- FeedbackRequestBody: Request body for POST /api/v1/feedback/request. Triggers a WhatsApp feedback template and enrolls the conversation into the tenant's feedback pipeline. Caller must supply EXACTLY ONE of: - order_id — UUID of an existing order in Elocuenti. Use this when the tenant tracks orders in Elocuenti. - external_reference — opaque string from the caller's own system (Shopify order number, ticket code, voucher ID, etc.). Use this when the tenant doesn't sync orders into Elocuenti. Optional: - idempotency_key — explicit dedup key. Defaults to order_id (as text) or external_reference. Dedup is per-tenant.
  - `phone` string, required: Customer phone in E.164 format.
  - `template_name` string, required: WhatsApp template name to send.
  - `template_params` object, nullable: Optional template variables. Keys must match the template's `parameter_mapping` (e.g. `customer_name`, `order_id`). Merged with defaults (`customer_name`, `order_id`).
  - `order_id` string, nullable: UUID of the order being asked about. Optional — omit for ticketing/marketplace flows that don't sync orders into Elocuenti.
  - `external_reference` string, nullable: Caller's own ID for the transaction (any string). Used for dedup when no order_id is available.
  - `idempotency_key` string, nullable: Explicit dedup key. Defaults to order_id (as text) or external_reference. To send AGAIN for an order that already has a row (e.g. to re-deliver a corrected link), pass a different key such as `<external_reference>-resend-1`: dedup is per (tenant, idempotency_key) only.
  - `batch_id` string, nullable: Optional caller-supplied batch identifier. Echoed verbatim into the structured logs so a whole send can be reconciled per batch (created / deduplicated / failed) with a single log query.
  - `customer_name` string, nullable
  - `customer_email` string, nullable
  - `fallback_template` string, nullable: Optional fallback template name if the primary is not found.
  - `from` string, nullable: Optional. The business WhatsApp number to send from, in E.164 (e.g. `+573001234567`). Omit it to send from the business default. A number that is not one of the business's active numbers is refused with 422 `from_number_not_available`.

## Response `200`

Successful Response

- FeedbackRequestResponse
  - `data` FeedbackRequest, required: `data` of the answer: 202 once sent or saved, 200 on dedup.
    - `feedback_request_id` string, nullable, required
    - `conversation_id` string, nullable, required
    - `status` 'feedback_request_sent' | 'feedback_saved_template_failed' | 'feedback_already_requested', required
    - `template_sent` boolean, required
    - `contact_id` string, nullable
    - `pipeline_instance_id` string, nullable
    - `template_used` string, nullable
    - `used_fallback` boolean, nullable
    - `template_error` string, nullable
    - `warning` string, nullable
    - `recovered_cart_id` string, nullable
    - `deduplicated` boolean, nullable
    - `code` string, nullable
    - `existing_status` string, nullable
    - `existing_sent_at` string, nullable
    - `existing_reference` string, nullable
    - `existing_created_at` string, nullable
    - `hint` string, nullable
    - `from` string, nullable: The business number the notice left from, in E.164. Present only when it already went out (not when it is queued, delegated to a workflow or saved without sending).
  - `request_id` string, nullable

## Other responses

- `202`: Aceptado: la petición es válida y el trabajo se completa de forma asíncrona. No implica que el efecto ya haya ocurrido.
- `400`: Petición malformada: una validación que el JSON Schema no puede expresar (reglas entre campos, headers de firma obligatorios ausentes) o un cuerpo que no es UTF-8. Un JSON roto en UTF-8 responde, en cambio, **422** `json_invalid`.
- `401`: No autenticado: falta la credencial, es inválida o expiró.
- `403`: Autenticado, pero sin permiso sobre este recurso o tenant.
- `409`: Conflicto con el estado actual del recurso.
- `422`: El cuerpo o los parámetros no pasan la validación del esquema.
- `429`: Se superó el límite de peticiones del API key o de la IP.
- `500`: Error interno no recuperable por el cliente.

---

[API](https://skmtc.dev/elocuenti/apis/elocuenti-api.md) · [All operations](https://skmtc.dev/elocuenti/apis/elocuenti-api/llms.txt) · [OpenAPI document](https://skmtc.dev/elocuenti/apis/elocuenti-api/revisions/633c2767ac8a?raw)