openapi: 3.0.1
info:
  title: Trengo Channels Labels and Custom Fields API
  description: REST API for the Trengo omnichannel customer-engagement platform. Manage tickets (conversations), contacts and profiles, messages, channels, teams and users, labels and custom fields, webhooks, and outbound WhatsApp templates across email, WhatsApp, live chat, voice, SMS, and social channels. All requests authenticate with a personal access token sent as an HTTP Bearer token.
  termsOfService: https://trengo.com/terms-conditions
  contact:
    name: Trengo Support
    url: https://developers.trengo.com/docs/welcome
  version: '2.0'
servers:
- url: https://app.trengo.com/api/v2
  description: Trengo REST API v2
security:
- bearerAuth: []
tags:
- name: Labels and Custom Fields
  description: Manage labels and custom fields.
paths:
  /tickets/{ticket_id}/labels:
    post:
      operationId: attachLabelToTicket
      tags:
      - Labels and Custom Fields
      summary: Attach a label to a ticket
      description: Attaches an existing label to a ticket.
      parameters:
      - $ref: '#/components/parameters/TicketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - label_id
              properties:
                label_id:
                  type: integer
                  format: int32
      responses:
        '200':
          description: Label attached.
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /custom_fields:
    post:
      operationId: createCustomField
      tags:
      - Labels and Custom Fields
      summary: Create a custom field
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              - type
              properties:
                title:
                  type: string
                type:
                  type: string
                  enum:
                  - TEXT
                  - NUMBER
                  - DATE
                  - DROPDOWN
      responses:
        '201':
          description: The created custom field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    TicketId:
      name: ticket_id
      in: path
      required: true
      schema:
        type: integer
        format: int32
  responses:
    TooManyRequests:
      description: Rate limit exceeded (120 requests per minute per token). Honor the Retry-After and X-RateLimit-Reset response headers.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp when the limit resets.
  schemas:
    CustomField:
      type: object
      properties:
        id:
          type: integer
          format: int32
        title:
          type: string
        type:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Personal access token generated in the Trengo account, sent as `Authorization: Bearer {TOKEN}`.'