openapi: 3.0.0
info:
  title: Exports API
  description: >-
    Welcome to the Dixa Exports API, which allows you to seamlessly stream
    up-to-date conversation and message data from the Dixa platform. This can be
    used to pull Dixa data into your own system, for warehousing purposes. For
    advanced analytics, BI reporting and audit purposes, have a look at our
    [Analytics API](https://docs.dixa.io/openapi/dixa-api/v1/tag/Analytics/).
  version: 1.0.0
servers:
  - url: https://exports.dixa.io
paths:
  /v1/conversation_export:
    get:
      summary: Returns a list of conversations.
      parameters:
        - name: closed_after
          in: query
          description: >-
            Filter for conversations closed after this date. Format should be
            yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
          example: '2022-01-01'
        - name: closed_before
          in: query
          description: >-
            Filter for conversations closed before this date. Format should be
            yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
          example: '1646151737080'
        - name: created_after
          in: query
          description: >-
            Filter for conversations created after this date. Format should be
            yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
        - name: created_before
          in: query
          description: >-
            Filter for conversations created before this date. Format should be
            yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
        - name: updated_after
          in: query
          description: >-
            Filter for conversations updated after this date. Format should be
            yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
        - name: updated_before
          in: query
          description: >-
            Filter for conversations updated before this date. Format should be
            yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
        - name: last_message_created_after
          in: query
          description: >-
            Filter for conversations where the last message was created after
            this date. Format should be yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
        - name: last_message_created_before
          in: query
          description: >-
            Filter for conversations where the last message was created before
            this date. Format should be yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
        - name: csids
          in: query
          description: Filter for this list of conversation IDs, comma separated
          required: false
          schema:
            type: array
            items:
              type: integer
              format: int32
          example: 123,456
      responses:
        '200':
          description: Array of conversations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationInfo'
        '400':
          description: Invalid query parameters
        '401':
          description: Invalid or missing credentials
        '429':
          description: API limit has been reached
        5XX:
          description: Internal error
  /v1/message_export:
    get:
      summary: Returns a list of messages.
      parameters:
        - name: created_after
          in: query
          description: >-
            Filter for conversations created after this date. Format should be
            yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
          example: '2022-01-01'
        - name: created_before
          in: query
          description: >-
            Filter for conversations created before this date. Format should be
            yyyy-mm-dd or Unix timestamp in ms
          required: false
          schema:
            type: string
            format: date
          example: '1646151737080'
      responses:
        '200':
          description: Array of messages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MessageInfo'
        '400':
          description: Invalid query parameters
        '401':
          description: Invalid or missing credentials
        '429':
          description: API limit has been reached
        5XX:
          description: Internal error
components:
  schemas:
    ConversationInfo:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: Id of the conversation
        created_at:
          type: integer
          format: int64
          description: Timestamp of when the conversation was created
        initial_channel:
          type: string
          description: The channel through which the communication was established
          example: email
        requester_id:
          type: string
          format: uuid
          description: Id of the enduser who requested the conversation
        requester_name:
          type: string
          description: Name of the enduser who requested the conversation
        requester_email:
          type: string
          description: Email of the enduser who requested the conversation
        requester_additional_emails:
          type: array
          items:
            type: string
          description: >-
            Additional email addresses of the enduser who requested the
            conversation
        requester_phone_number:
          type: string
          description: Phone number of the enduser who requested the conversation
        requester_additional_phone_numbers:
          type: array
          items:
            type: string
          description: >-
            Additional phone numbers of the enduser who requested the
            conversation
        queued_at:
          type: number
          format: int64
          description: Timestamp of when the conversation was queued
        queue_id:
          type: string
          format: uuid
          description: Id of the last queue where the conversation was placed
        queue_name:
          type: string
          description: Name of the last queue where the conversation was placed
        closed_at:
          type: number
          format: int64
          description: Timestamp of when the conversation was closed
        rating_score:
          type: integer
          format: int32
          enum:
            - 0
            - 1
          description: >-
            Rating score. This field is only relevant if you have set up the
            thumbs up/down ratings
          deprecated: true
        rating_message:
          type: string
          description: >-
            Rating message associated with the rating score. This field is only
            relevant if you have set up the thumbs up/down ratings
          deprecated: true
        ratings:
          type: array
          items:
            $ref: '#/components/schemas/Rating'
        direction:
          type: string
          enum:
            - inbound
            - outbound
          description: Direction of the conversation
        assigned_at:
          type: integer
          format: int64
          description: Timestamp of when the conversation was assigned to an agent
        assignee_id:
          type: string
          format: uuid
          description: Id of the agent that the conversation was assigned to
        assignee_name:
          type: string
          description: Name of the agent that the conversation was assigned to
        assignee_email:
          type: string
          description: Email of the agent that the conversation was assigned to
        assignee_phone_number:
          type: string
          description: Phone number of the agent that the conversation was assigned to
        to_provisioned_phone_number_id:
          type: string
          description: >-
            Called phone number id (for inbound calls), which is the phone
            number itself
        to_provisioned_phone_number_name:
          type: string
          description: Name of the called phone number provided
        total_duration:
          type: number
          format: int64
          description: >-
            Call duration in seconds if it exists. This is a derived value
            `closed_at` - `created_at`. For advanced analytics, take a look at
            our [Analytics
            API](https://docs.dixa.io/openapi/dixa-api/v1/tag/Analytics/).
          deprecated: true
        handling_duration:
          type: number
          format: int64
          description: >-
            Handling duration in seconds. This is a derived value `closed_at` -
            `assigned_at`. For advanced analytics, take a look at our [Analytics
            API](https://docs.dixa.io/openapi/dixa-api/v1/tag/Analytics/).
          deprecated: true
        dixa_email_integration_id:
          type: string
          description: Id of the email integration, which is the email address itself
        dixa_email_integration_sender_name:
          type: string
          description: Sender name of the email integration, if it exists
        forwarding_email:
          type: string
          description: Forwarding email address
        facebook_page_id:
          type: string
          description: Page id coming from facebook
        facebook_page_name:
          type: string
          description: Page name coming from facebook
        widget_id:
          type: string
          format: uuid
          description: Id of the widget that was used
        widget_name:
          type: string
          description: Name of the widget that was used
        tags:
          type: array
          items:
            type: string
          description: All tags associated with the conversation
        tags_info:
          type: array
          items:
            type: string
          description: All tags info associated with the conversation
        conversation_wrapup_notes:
          type: array
          items:
            type: string
          description: All notes associated with the conversation
        transferee_name:
          type: string
          description: >-
            Target entity name of the transfer, which is either a queue or a
            user
        transfer_time:
          type: number
          format: int64
          description: Timestamp of the latest transfer
        originating_country:
          type: string
          description: Country the conversation originates from
        updated_at:
          type: number
          format: int64
          description: Timestamp of when the conversation was last time updated
        last_message_created_at:
          type: number
          format: int64
          description: Timestamp of when the last associated message was created
        status:
          type: string
          enum:
            - open
            - closed
            - pending
            - awaitingpending
          description: Status of the conversation
        transferee_number:
          type: string
          description: Phone number of the agent to whom the conversation was transferred
        from_provisioned_phone_number_id:
          type: string
          description: >-
            Calling phone number id (for outbound calls), which is the phone
            number itself
        from_provisioned_phone_number_name:
          type: string
          description: Name of the calling phone number provided
        subject:
          type: string
          description: Subject field (for email and contact form)
        anonymized_at:
          type: number
          format: int64
          description: Timestamp of when the conversation was anonymized
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttribute'
        exports_handling_duration:
          type: number
          format: int64
          description: >-
            Cumulative assignment time across all agents that handled the
            conversation (in seconds). Can be different from
            `handling_duration`. This value corresponds to the handling_duration
            field in the "Integrations -> Export Conversations" CSV file.
        link_type:
          type: string
          enum:
            - email_forward
            - follow_up
            - side
            - related
          description: Type of link associated with the conversation
          example: side
        linked_at:
          type: integer
          format: int64
          description: Timestamp of when the conversation was linked
          example: 1762787749131
        linked_to:
          type: integer
          format: int32
          description: ID of the conversation this conversation is linked to
          example: 14665
      required:
        - id
        - created_at
        - initial_channel
        - requester_id
    Rating:
      type: object
      properties:
        rating_score:
          type: integer
          format: int32
          description: >-
            Rating score. Score will be 0 or 1 for thumbs up & down ratings or
            1-5 for new CSAT ratings
        rating_message:
          type: string
          description: Rating message associated with the rating score
        rating_type:
          type: string
          description: Rating type associated with the rating score
          example: stars
        rating_created_timestamp:
          type: integer
          format: int64
          description: Timestamp of when the CSAT was created
        rating_offered_timestamp:
          type: integer
          format: int64
          description: Timestamp of when the CSAT was offered
        rating_status:
          type: string
          description: Status associated with the rating
          example: rated
        rating_language:
          type: string
          description: Language set for the conversation
          example: en
        rating_modified_timestamp:
          type: integer
          format: int64
          description: Timestamp of when the rating was lastly modified
        rating_rated_timestamp:
          type: integer
          format: int64
          description: Timestamp of when the conversation was rated
        rating_scheduled_timestamp:
          type: integer
          format: int64
          description: Timestamp of when the CSAT was scheduled
        rating_scheduled_for_timestamp:
          type: integer
          format: int64
          description: Timestamp of when the CSAT was scheduled for
        rating_unscheduled_timestamp:
          type: integer
          format: int64
          description: Timestamp of when the CSAT was unscheduled
        rating_cancelled_timestamp:
          type: integer
          format: int64
          description: Timestamp of when the CSAT was cancelled
    CustomAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          format: uuid
          description: Custom attribute UUID
        identifier:
          type: string
          description: Custom attribute identifier
        value:
          type: string
          description: The custom attribute value set for the conversation
        data_type:
          type: string
          description: Custom attribute type
        archived:
          type: boolean
          description: Whether the custom attribute has been archived
    MessageInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the message
        csid:
          type: integer
          format: int32
          description: Id of the conversation the message belongs to
        created_at:
          type: integer
          format: int64
          description: Timestamp of when the message was created
        initial_channel:
          type: string
          description: The channel through which the communication was established
          example: widgetchat
        author_name:
          type: string
          description: Name of the author of the message
        author_email:
          type: string
          description: Email of the author of the message
        direction:
          type: string
          enum:
            - inbound
            - outbound
          description: Direction of the conversation
        text:
          type: string
          description: >-
            The full message text. Not relevant for PSTN phone and voicemail
            channels
        from_phone_number:
          type: string
          description: >-
            Phone number the conversation was initiated from. Relevant only for
            PTSN phone and voicemail channels
        to_phone_number:
          type: string
          description: >-
            Phone number the conversation was aimed for. Relevant only for PTSN
            phone and voicemail channels
        duration:
          type: number
          format: int64
          description: >-
            Length of the call/voicemail. Relevant only for PTSN phone and
            voicemail channels
        recording_url:
          type: string
          description: >-
            Link to the recording of the call. Relevant only for PTSN phone
            channel
        voicemail_url:
          type: string
          description: Link to the voicemail. Relevant only for voicemail channel
        to:
          type: array
          items:
            type: string
          description: >-
            Email address(es) a conversation was aimed for. Relevant only for
            email and contact form channels
        from:
          type: string
          description: >-
            Email address a conversation was initiated from. Relevant only for
            email and contact form channels
        cc:
          type: array
          items:
            type: string
          description: >-
            Email address(es) included in the email as CC. Relevant only for
            email channel
        bcc:
          type: array
          items:
            type: string
          description: >-
            Email address(es) included in the email as BCC. Relevant only for
            email channel
        attached_files:
          type: array
          items:
            type: string
          description: >-
            Link(s) to files that have been attached to the message. Relevant
            only for email and Facebook Messenger channel
        is_automated_message:
          type: boolean
          description: >-
            Whether a message has been generated automatically or by an agent.
            Relevant only for widget chat
        chat_input_question:
          type: string
          description: >-
            Input question initiating the conversation. Relevant only for widget
            chat
          example: How can we help?
        chat_input_answer:
          type: string
          description: >-
            Input answer initiating the conversation. Relevant only for widget
            chat
          example: None of the above
        chat_menu_text:
          type: string
          description: Menu text initiating the conversation. Relevant only for widget chat
          example: Please input your order number.
        form_submission:
          type: object
          description: >-
            Form submission associated with the message. Relevant only for
            Messenger and ContactForm channels
          example:
            name: John Doe
            email: johndoe@gmail.com
            phone: '+4512345678'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
security:
  - BearerAuth: []
