openapi: 3.0.1
info:
  title: Trengo 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: Tickets
    description: Create, list, assign, label, and close conversations.
  - name: Messages
    description: List and send text and media messages on a ticket.
  - name: Contacts
    description: Manage contacts and contact profiles.
  - name: Channels
    description: List connected channels.
  - name: Teams and Users
    description: Manage teams and list agents.
  - name: Labels and Custom Fields
    description: Manage labels and custom fields.
  - name: Webhooks
    description: Register and manage webhook subscriptions.
  - name: WhatsApp
    description: Send approved WhatsApp Business templates.
paths:
  /tickets:
    get:
      operationId: listTickets
      tags:
        - Tickets
      summary: List all tickets
      description: Returns all tickets the authenticated user is authorized to see.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: status
          in: query
          description: Filter by ticket status.
          schema:
            type: string
            enum: [OPEN, ASSIGNED, CLOSED, INVALID]
        - name: contact_id
          in: query
          schema:
            type: integer
            format: int32
        - name: users[]
          in: query
          schema:
            type: array
            items:
              type: integer
              format: int32
        - name: channels[]
          in: query
          schema:
            type: array
            items:
              type: integer
              format: int32
        - name: labels[]
          in: query
          schema:
            type: array
            items:
              type: integer
              format: int32
        - name: last_message_type
          in: query
          schema:
            type: string
            enum: [INBOUND, OUTBOUND]
        - name: sort
          in: query
          schema:
            type: string
            default: '-date'
        - name: updated_at_gt
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: A paginated list of tickets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketList'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createTicket
      tags:
        - Tickets
      summary: Create a ticket
      description: Creates a new ticket on a channel for a given contact identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTicketRequest'
      responses:
        '201':
          description: The created ticket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /tickets/{ticket_id}/assign:
    patch:
      operationId: assignTicket
      tags:
        - Tickets
      summary: Assign a ticket
      description: Assigns a ticket to a user and/or a team.
      parameters:
        - $ref: '#/components/parameters/TicketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignTicketRequest'
      responses:
        '200':
          description: The updated ticket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /tickets/{ticket_id}/close:
    patch:
      operationId: closeTicket
      tags:
        - Tickets
      summary: Close a ticket
      description: Marks a ticket as closed.
      parameters:
        - $ref: '#/components/parameters/TicketId'
      responses:
        '200':
          description: The closed ticket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /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'
  /tickets/{ticket_id}/messages:
    get:
      operationId: listMessages
      tags:
        - Messages
      summary: List all messages
      description: Returns all messages for the given ticket.
      parameters:
        - $ref: '#/components/parameters/TicketId'
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: A paginated list of messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: sendMessage
      tags:
        - Messages
      summary: Send a ticket message
      description: Sends an outbound text message on the ticket's channel.
      parameters:
        - $ref: '#/components/parameters/TicketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '201':
          description: The sent message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /tickets/{ticket_id}/messages/media:
    post:
      operationId: sendMediaMessage
      tags:
        - Messages
      summary: Send a ticket media message
      description: Sends an outbound message with one or more media attachments.
      parameters:
        - $ref: '#/components/parameters/TicketId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                body:
                  type: string
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: The sent media message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /contacts:
    get:
      operationId: listContacts
      tags:
        - Contacts
      summary: List contacts
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: term
          in: query
          description: Search term to filter contacts.
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createContact
      tags:
        - Contacts
      summary: Create a contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactRequest'
      responses:
        '201':
          description: The created contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /contacts/{contact_id}:
    get:
      operationId: getContact
      tags:
        - Contacts
      summary: Get a contact
      parameters:
        - $ref: '#/components/parameters/ContactId'
      responses:
        '200':
          description: The contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    put:
      operationId: updateContact
      tags:
        - Contacts
      summary: Update a contact
      parameters:
        - $ref: '#/components/parameters/ContactId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactRequest'
      responses:
        '200':
          description: The updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteContact
      tags:
        - Contacts
      summary: Delete a contact
      parameters:
        - $ref: '#/components/parameters/ContactId'
      responses:
        '204':
          description: Contact deleted.
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channels/voice:
    get:
      operationId: listVoiceChannels
      tags:
        - Channels
      summary: List all voice channels
      responses:
        '200':
          description: A list of voice channels.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /teams:
    post:
      operationId: createTeam
      tags:
        - Teams and Users
      summary: Create a team
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        '201':
          description: The created team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /users:
    get:
      operationId: listUsers
      tags:
        - Teams and Users
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: A paginated list of users (agents).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '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'
  /webhooks:
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: The created webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /webhooks/{webhook_id}:
    put:
      operationId: updateWebhook
      tags:
        - Webhooks
      summary: Update a webhook
      parameters:
        - $ref: '#/components/parameters/WebhookId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '200':
          description: The updated webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook
      parameters:
        - $ref: '#/components/parameters/WebhookId'
      responses:
        '204':
          description: Webhook deleted.
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /whatsapp/messages:
    post:
      operationId: sendWhatsAppTemplate
      tags:
        - WhatsApp
      summary: Send a WhatsApp template
      description: >-
        Sends a pre-approved WhatsApp Business message template to a contact
        on a WhatsApp channel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendWhatsAppTemplateRequest'
      responses:
        '201':
          description: The sent template message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token generated in the Trengo account, sent as
        `Authorization: Bearer {TOKEN}`.
  parameters:
    TicketId:
      name: ticket_id
      in: path
      required: true
      schema:
        type: integer
        format: int32
    ContactId:
      name: contact_id
      in: path
      required: true
      schema:
        type: integer
        format: int32
    WebhookId:
      name: webhook_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:
    Ticket:
      type: object
      properties:
        id:
          type: integer
          format: int32
        subject:
          type: string
        status:
          type: string
          enum: [OPEN, ASSIGNED, CLOSED, INVALID]
        contact:
          $ref: '#/components/schemas/Contact'
        channel:
          $ref: '#/components/schemas/Channel'
        assignee:
          $ref: '#/components/schemas/User'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TicketList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Ticket'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    CreateTicketRequest:
      type: object
      required: [channel_id, contact_identifier]
      properties:
        channel_id:
          type: integer
          format: int32
          description: The channel the ticket should be opened on.
        contact_identifier:
          type: string
          description: Phone number, email, or other identifier for the contact.
        subject:
          type: string
        delegate_to_user_id:
          type: integer
          format: int32
        delegate_to_team_id:
          type: integer
          format: int32
    AssignTicketRequest:
      type: object
      properties:
        user_id:
          type: integer
          format: int32
        team_id:
          type: integer
          format: int32
    Message:
      type: object
      properties:
        id:
          type: integer
          format: int32
        ticket_id:
          type: integer
          format: int32
        body:
          type: string
        type:
          type: string
          enum: [INBOUND, OUTBOUND]
        attachments:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              filename:
                type: string
        created_at:
          type: string
          format: date-time
    MessageList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    SendMessageRequest:
      type: object
      required: [body]
      properties:
        body:
          type: string
          description: The message text to send.
        internal_note:
          type: boolean
          description: When true, posts an internal note instead of an outbound message.
    Contact:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        identifier:
          type: string
        email:
          type: string
        phone:
          type: string
        created_at:
          type: string
          format: date-time
    ContactList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    CreateContactRequest:
      type: object
      required: [name, identifier, channel_id]
      properties:
        name:
          type: string
        identifier:
          type: string
          description: Phone number or email used to reach the contact.
        channel_id:
          type: integer
          format: int32
        email:
          type: string
        phone:
          type: string
    Channel:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        type:
          type: string
          description: Channel type, e.g. EMAIL, WA_BUSINESS, CHAT, VOIP, SMS.
    Team:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
    User:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        email:
          type: string
        is_admin:
          type: boolean
    CustomField:
      type: object
      properties:
        id:
          type: integer
          format: int32
        title:
          type: string
        type:
          type: string
    CreateWebhookRequest:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint that receives event callbacks.
        name:
          type: string
    Webhook:
      type: object
      properties:
        id:
          type: integer
          format: int32
        url:
          type: string
          format: uri
        name:
          type: string
    SendWhatsAppTemplateRequest:
      type: object
      required: [recipient_phone_number, hsm_id, channel_id]
      properties:
        recipient_phone_number:
          type: string
          description: E.164 phone number of the WhatsApp recipient.
        hsm_id:
          type: integer
          format: int32
          description: The approved WhatsApp template (HSM) identifier.
        channel_id:
          type: integer
          format: int32
        params:
          type: array
          description: Ordered template parameter values.
          items:
            type: object
            properties:
              type:
                type: string
              key:
                type: string
              value:
                type: string
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        last_page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer