Elocuenti Feedback API

openapi: 3.2.0
info:
  title: Elocuenti Feedback API
  version: 1.0.0
  description: 'The public REST API of Elocuenti: contacts, conversations, funnels, WhatsApp templates, knowledge base, automations, events, AI calls, webhooks and charges (Colombia).


    Authenticate every request with `Authorization: Bearer `. A key that starts with `eloc_live_` acts in production; one that starts with `eloc_sand_` is a sandbox key: it never messages or calls your customers, and the **Sandbox** line of each operation says what it does instead. Create keys in Settings → API Keys.


    Guides and reference: https://www.elocuenti.com/api/docs'
servers:
- url: https://www.elocuenti.com
tags:
- name: Feedback
paths:
  /api/v1/feedback/request:
    post:
      tags:
      - Feedback
      summary: Ask for feedback on a purchase
      description: 'Sends your survey template by WhatsApp and puts the conversation in your feedback funnel, where the AI collects the rating and the comment.


        It answers `202` with `feedback_request_sent` or `feedback_saved_template_failed` (saved, the template failed). The same `idempotency_key` answers `200` with `feedback_already_requested` and never writes twice.


        **Permission:** `messages:write` · **Sandbox:** checked, nothing is saved or sent (`simulated: true`) · **Idempotency:** `idempotency_key` in the body · **Max body:** 5 MB'
      operationId: create_feedback_request
      security:
      - ApiKey: []
      x-access:
        permission: messages:write
        sandbox: simulate
        idempotencyField: idempotency_key
        maxBody: 5 MB
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequestBody'
            examples:
              feedback:
                summary: Ask about a delivered order
                value:
                  phone: '+573001234567'
                  template_name: order_feedback
                  external_reference: order-1042
                  customer_name: Ana Gómez
                  template_params:
                    '1': Ana
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackRequestResponse'
        '202':
          description: 'Accepted: the request is valid and the work finishes asynchronously. It does not mean the effect already happened.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackRequestResponse'
        '400':
          description: 'Malformed request: a rule the JSON Schema cannot express (between fields, a required signature header that is missing) or a body that is not UTF-8. Broken JSON in UTF-8 answers **422** `json_invalid` instead.'
        '401':
          description: 'Not authenticated: the API key is missing, invalid or expired.'
        '403':
          description: Authenticated, but without permission for this resource or business.
        '409':
          description: Conflicts with the current state of the resource.
        '422':
          description: The body or the parameters fail the schema's validation.
        '429':
          description: The API key or the IP went over its request limit.
        '500':
          description: 'Internal error: there is nothing the client can change to fix it.'
components:
  schemas:
    FeedbackRequest:
      type: object
      properties:
        feedback_request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Feedback Request Id
        conversation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Conversation Id
        status:
          type: string
          enum:
          - feedback_request_sent
          - feedback_saved_template_failed
          - feedback_already_requested
          title: Status
        template_sent:
          type: boolean
          title: Template Sent
        contact_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Id
        pipeline_instance_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipeline Instance Id
        template_used:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Used
        used_fallback:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Used Fallback
        template_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Error
        warning:
          anyOf:
          - type: string
          - type: 'null'
          title: Warning
        recovered_cart_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Recovered Cart Id
        deduplicated:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Deduplicated
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
        existing_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Existing Status
        existing_sent_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Existing Sent At
        existing_reference:
          anyOf:
          - type: string
          - type: 'null'
          title: Existing Reference
        existing_created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Existing Created At
        hint:
          anyOf:
          - type: string
          - type: 'null'
          title: Hint
        from:
          anyOf:
          - type: string
          - type: 'null'
          description: 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).
          title: From
      required:
      - feedback_request_id
      - conversation_id
      - status
      - template_sent
      description: '`data` of the answer: 202 once sent or saved, 200 on dedup.'
      title: FeedbackRequest
    FeedbackRequestResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/FeedbackRequest'
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - 3f9a1c07d2b4
          title: Request Id
        simulated:
          description: '`true` only with a sandbox key: the request was checked in full and nothing was sent or saved.'
          type: boolean
          title: Simulated
      required:
      - data
      title: FeedbackRequestResponse
    FeedbackRequestBody:
      type: object
      properties:
        phone:
          type: string
          minLength: 10
          description: Customer phone in E.164 format.
          title: Phone
        template_name:
          type: string
          minLength: 1
          description: WhatsApp template name to send.
          title: Template Name
        template_params:
          description: Optional template variables. Keys must match the template's `parameter_mapping` (e.g. `customer_name`, `order_id`). Merged with defaults (`customer_name`, `order_id`).
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          title: Template Params
        order_id:
          anyOf:
          - type: string
          - type: 'null'
          description: UUID of the order being asked about. Optional — omit for ticketing/marketplace flows that don't sync orders into Elocuenti.
          title: Order Id
        external_reference:
          description: Caller's own ID for the transaction (any string). Used for dedup when no order_id is available.
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: External Reference
        idempotency_key:
          description: '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.'
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Idempotency Key
        batch_id:
          description: 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.
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Batch Id
        customer_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Name
        customer_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Email
        fallback_template:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional fallback template name if the primary is not found.
          title: Fallback Template
        from:
          anyOf:
          - type: string
          - type: 'null'
          description: 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`.
          title: From
      required:
      - phone
      - template_name
      description: 'Send exactly one of `order_id` (an order in Elocuenti) or `external_reference` (your own order number). `idempotency_key` is optional: without it the key is `order_id` (as text) or else `external_reference`, within your business, so the same order never gets two surveys.'
      title: FeedbackRequestBody
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key