openapi: 3.0.1
info:
  title: Trengo Channels Contacts 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: Contacts
  description: Manage contacts and contact profiles.
paths:
  /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'
components:
  parameters:
    ContactId:
      name: contact_id
      in: path
      required: true
      schema:
        type: integer
        format: int32
  schemas:
    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
    ContactList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    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
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        last_page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
  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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Personal access token generated in the Trengo account, sent as `Authorization: Bearer {TOKEN}`.'