@crvouga/mockingbird-service-intercom 1.9.0 → 2.0.0

package/openapi.yaml

@@ -0,0 +1,1078 @@
+openapi: 3.1.0
+info:
+  title: Intercom REST API 2.11 (Mockingbird subset)
+  description: |
+    Stateful mock subset of the Intercom REST API (version 2.11): contacts (search, create,
+    update, get), conversations (create, update, reply as user or admin with attachments,
+    close/open/snooze/assign, get, search) and the admin identity endpoints. Covers the backend's
+    member messaging adapter and the Intercom sync adapter.
+  version: "2.11"
+  x-mockingbird-upstream:
+    note: >-
+      Trimmed from Intercom's published 2.11 API reference to the operations and fields our
+      consumers use (intercom-messaging.adapter.ts, intercom-api.adapter.ts) and the webhook
+      receivers (messaging.controller.ts, the EMR IntercomWebhookService).
+servers:
+  - url: https://api.intercom.io
+security:
+  - bearerAuth: []
+paths:
+  /contacts/search:
+    post:
+      operationId: SearchContacts
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [query]
+              properties:
+                query:
+                  $ref: "#/components/schemas/ContactQuery"
+                pagination:
+                  $ref: "#/components/schemas/Pagination"
+      responses:
+        "200":
+          description: Matching contacts
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ContactList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /contacts:
+    post:
+      operationId: CreateContact
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ContactCreate"
+      responses:
+        "200":
+          description: The created contact
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Contact"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /contacts/{contact_id}:
+    parameters:
+      - name: contact_id
+        in: path
+        required: true
+        schema:
+          type: string
+          x-mockingbird-resource-ref:
+            type: contact
+            missing: 000000000000000000000000
+    get:
+      operationId: GetContact
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        "200":
+          description: The contact
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Contact"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    put:
+      operationId: UpdateContact
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ContactUpdate"
+      responses:
+        "200":
+          description: The updated contact
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Contact"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /conversations:
+    post:
+      operationId: CreateConversation
+      description: A contact-initiated conversation. An optional `Idempotency-Key` header replays.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          schema:
+            type: string
+            pattern: "^[A-Za-z0-9_-]{1,40}$"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [from, body]
+              properties:
+                from:
+                  type: object
+                  required: [type, id]
+                  properties:
+                    type:
+                      type: string
+                      enum: [user, lead, contact]
+                    id:
+                      type: string
+                      x-mockingbird-resource-ref:
+                        type: contact
+                        missing: 000000000000000000000000
+                body:
+                  type: string
+                  minLength: 1
+                  maxLength: 400
+                created_at:
+                  type: integer
+                  minimum: 1600000000
+                  maximum: 1900000000
+      responses:
+        "200":
+          description: The first message of the new conversation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /conversations/search:
+    post:
+      operationId: SearchConversations
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/DisplayAs"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [query]
+              properties:
+                query:
+                  $ref: "#/components/schemas/ConversationQuery"
+                pagination:
+                  $ref: "#/components/schemas/Pagination"
+                sort_field:
+                  type: string
+                  enum: [updated_at, created_at, id, waiting_since]
+                sort_order:
+                  type: string
+                  enum: [ascending, descending]
+      responses:
+        "200":
+          description: A page of matching conversations (without conversation parts)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConversationList"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /conversations/{conversation_id}:
+    parameters:
+      - $ref: "#/components/parameters/ConversationId"
+    get:
+      operationId: GetConversation
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/DisplayAs"
+      responses:
+        "200":
+          description: The conversation with its parts
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Conversation"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    put:
+      operationId: UpdateConversation
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      parameters:
+        - $ref: "#/components/parameters/DisplayAs"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                read:
+                  type: boolean
+                title:
+                  type: string
+                  maxLength: 120
+                custom_attributes:
+                  type: object
+                  maxProperties: 4
+                  additionalProperties:
+                    type: [string, number, boolean, "null"]
+      responses:
+        "200":
+          description: The updated conversation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Conversation"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /conversations/{conversation_id}/reply:
+    parameters:
+      - $ref: "#/components/parameters/ConversationId"
+    post:
+      operationId: ReplyConversation
+      description: >-
+        Reply as the contact (`type: user` + `intercom_user_id`) or as an admin (`type: admin`
+        + `admin_id`), as JSON (attachments as base64 `attachment_files`) or multipart
+        (`attachment_files[]` file parts). Admin comments fire `conversation.admin.replied`.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ReplyBody"
+          multipart/form-data:
+            schema:
+              type: object
+              required: [message_type, type]
+              properties:
+                message_type:
+                  type: string
+                type:
+                  type: string
+                intercom_user_id:
+                  type: string
+                admin_id:
+                  type: string
+                body:
+                  type: string
+                attachment_files[]:
+                  type: array
+                  items:
+                    type: string
+                    format: binary
+      responses:
+        "200":
+          description: The conversation, with the new part
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Conversation"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /conversations/{conversation_id}/parts:
+    parameters:
+      - $ref: "#/components/parameters/ConversationId"
+    post:
+      operationId: ManageConversation
+      description: Close, open, snooze or assign; close and open fire `conversation.admin.closed` / `opened`.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [message_type, type, admin_id]
+              properties:
+                message_type:
+                  type: string
+                  enum: [close, open, snoozed, assignment]
+                type:
+                  type: string
+                  enum: [admin]
+                admin_id:
+                  type: string
+                  x-mockingbird-resource-ref:
+                    type: admin
+                    missing: "9999999"
+                body:
+                  type: string
+                  maxLength: 400
+                snoozed_until:
+                  type: integer
+                  minimum: 1600000000
+                  maximum: 1900000000
+                assignee_id:
+                  type: string
+                  x-mockingbird-resource-ref:
+                    type: admin
+                    missing: "9999999"
+      responses:
+        "200":
+          description: The conversation, with the new part
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Conversation"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /admins:
+    get:
+      operationId: ListAdmins
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        "200":
+          description: The workspace's admins
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [type, admins]
+                properties:
+                  type:
+                    type: string
+                    enum: [admin.list]
+                  admins:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Admin"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /me:
+    get:
+      operationId: GetMe
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        "200":
+          description: The admin that owns the access token
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [type, id, email, app]
+                properties:
+                  type:
+                    type: string
+                    enum: [admin]
+                  id:
+                    type: string
+                  name:
+                    type: string
+                  email:
+                    type: string
+                  email_verified:
+                    type: boolean
+                  has_inbox_seat:
+                    type: boolean
+                  avatar:
+                    type: object
+                  app:
+                    type: object
+                    required: [type, id_code]
+                    properties:
+                      type:
+                        type: string
+                      id_code:
+                        type: string
+                      name:
+                        type: string
+                      created_at:
+                        type: integer
+                      secure:
+                        type: boolean
+                      identity_verification:
+                        type: boolean
+                      timezone:
+                        type: string
+                      region:
+                        type: string
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    ConversationId:
+      name: conversation_id
+      in: path
+      required: true
+      schema:
+        type: string
+        x-mockingbird-resource-ref:
+          type: conversation
+          missing: "999999999999999"
+    DisplayAs:
+      name: display_as
+      in: query
+      schema:
+        type: string
+        enum: [plaintext]
+  responses:
+    BadRequest:
+      description: Invalid parameters
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
+    Unauthorized:
+      description: Missing or invalid access token
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
+    NotFound:
+      description: Unknown resource
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
+    Conflict:
+      description: A contact with that external_id or email already exists (or an idempotency conflict)
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
+  schemas:
+    ErrorList:
+      type: object
+      required: [type, errors]
+      properties:
+        type:
+          type: string
+          enum: [error.list]
+        request_id:
+          type: string
+          x-mockingbird-volatile:
+            kind: token
+        errors:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required: [code, message]
+            properties:
+              code:
+                type: string
+              message:
+                type: string
+    Pagination:
+      type: object
+      properties:
+        per_page:
+          type: integer
+          minimum: 1
+          maximum: 150
+        starting_after:
+          type: string
+          maxLength: 80
+    ContactFilter:
+      type: object
+      required: [field, operator, value]
+      properties:
+        field:
+          type: string
+          enum: [external_id, email, id, name, role, phone]
+        operator:
+          type: string
+          enum: ["=", "!=", "~", "!~", "^", "$", IN, NIN]
+        value:
+          oneOf:
+            - type: string
+              maxLength: 80
+            - type: array
+              maxItems: 3
+              items:
+                type: string
+                maxLength: 80
+    ContactQuery:
+      oneOf:
+        - $ref: "#/components/schemas/ContactFilter"
+        - type: object
+          required: [operator, value]
+          properties:
+            operator:
+              type: string
+              enum: [AND, OR]
+            value:
+              type: array
+              minItems: 1
+              maxItems: 3
+              items:
+                $ref: "#/components/schemas/ContactFilter"
+    ConversationFilter:
+      type: object
+      required: [field, operator, value]
+      properties:
+        field:
+          type: string
+          enum:
+            - id
+            - contact_ids
+            - admin_assignee_id
+            - team_assignee_id
+            - state
+            - open
+            - read
+            - created_at
+            - updated_at
+            - source.author.email
+            - source.delivered_as
+        operator:
+          type: string
+          enum: ["=", "!=", "<", ">", "~", IN, NIN]
+        value:
+          oneOf:
+            - type: string
+              maxLength: 80
+            - type: integer
+            - type: boolean
+            - type: array
+              maxItems: 3
+              items:
+                type: string
+                maxLength: 80
+    ConversationQuery:
+      oneOf:
+        - $ref: "#/components/schemas/ConversationFilter"
+        - type: object
+          required: [operator, value]
+          properties:
+            operator:
+              type: string
+              enum: [AND, OR]
+            value:
+              type: array
+              minItems: 1
+              maxItems: 3
+              items:
+                $ref: "#/components/schemas/ConversationFilter"
+    CustomAttributes:
+      type: object
+      maxProperties: 30
+      additionalProperties:
+        type: [string, number, boolean, "null"]
+    ContactCreate:
+      type: object
+      properties:
+        role:
+          type: string
+          enum: [user, lead]
+        external_id:
+          description: >-
+            Any string. The first branch steers the walk generator toward a few values, so
+            random walks reach the duplicate (409) path.
+          anyOf:
+            - type: string
+              pattern: "^[1-4]$"
+            - type: string
+              minLength: 1
+              maxLength: 64
+        email:
+          type: string
+          format: email
+          maxLength: 120
+        name:
+          type: ["string", "null"]
+          maxLength: 80
+        phone:
+          type: ["string", "null"]
+          maxLength: 40
+        signed_up_at:
+          type: ["integer", "null"]
+          minimum: 1000000000
+          maximum: 1900000000
+        last_seen_at:
+          type: ["integer", "null"]
+          minimum: 1000000000
+          maximum: 1900000000
+        custom_attributes:
+          $ref: "#/components/schemas/CustomAttributes"
+    ContactUpdate:
+      allOf:
+        - $ref: "#/components/schemas/ContactCreate"
+    ReplyBody:
+      type: object
+      required: [message_type, type]
+      properties:
+        message_type:
+          type: string
+          enum: [comment, note, quick_reply]
+        type:
+          type: string
+          enum: [user, admin]
+        body:
+          type: string
+          maxLength: 400
+        intercom_user_id:
+          type: string
+          x-mockingbird-resource-ref:
+            type: contact
+            missing: 000000000000000000000000
+        user_id:
+          type: string
+          maxLength: 64
+        email:
+          type: string
+          maxLength: 120
+        admin_id:
+          type: string
+          x-mockingbird-resource-ref:
+            type: admin
+            missing: "9999999"
+        created_at:
+          type: integer
+          minimum: 1600000000
+          maximum: 1900000000
+        attachment_urls:
+          type: array
+          maxItems: 3
+          items:
+            type: string
+            maxLength: 200
+        attachment_files:
+          type: array
+          maxItems: 3
+          items:
+            type: object
+            required: [content_type, data, name]
+            properties:
+              content_type:
+                type: string
+                maxLength: 80
+              data:
+                type: string
+                maxLength: 400
+              name:
+                type: string
+                minLength: 1
+                maxLength: 80
+    Contact:
+      type: object
+      required: [type, id, role, created_at, updated_at, custom_attributes]
+      properties:
+        type:
+          type: string
+          enum: [contact]
+        id:
+          type: string
+          x-mockingbird-resource:
+            type: contact
+            identity: true
+        workspace_id:
+          type: string
+        external_id:
+          type: ["string", "null"]
+        role:
+          type: string
+        email:
+          type: ["string", "null"]
+        phone:
+          type: ["string", "null"]
+        name:
+          type: ["string", "null"]
+        avatar:
+          type: ["string", "null"]
+        owner_id:
+          type: ["integer", "null"]
+        has_hard_bounced:
+          type: boolean
+        marked_email_as_spam:
+          type: boolean
+        unsubscribed_from_emails:
+          type: boolean
+        created_at:
+          type: integer
+          x-mockingbird-volatile:
+            kind: timestamp
+        updated_at:
+          type: integer
+          x-mockingbird-volatile:
+            kind: timestamp
+        signed_up_at:
+          type: ["integer", "null"]
+        last_seen_at:
+          type: ["integer", "null"]
+        custom_attributes:
+          type: object
+        tags:
+          type: object
+        notes:
+          type: object
+        companies:
+          type: object
+        location:
+          type: object
+        social_profiles:
+          type: object
+    Pages:
+      type: object
+      required: [type, page, per_page, total_pages]
+      properties:
+        type:
+          type: string
+          enum: [pages]
+        page:
+          type: integer
+        per_page:
+          type: integer
+        total_pages:
+          type: integer
+        next:
+          type: object
+          required: [page, starting_after]
+          properties:
+            page:
+              type: integer
+            starting_after:
+              type: string
+    ContactList:
+      type: object
+      required: [type, data, total_count, pages]
+      properties:
+        type:
+          type: string
+          enum: [list]
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/Contact"
+        total_count:
+          type: integer
+        pages:
+          $ref: "#/components/schemas/Pages"
+    Author:
+      type: object
+      required: [type, id]
+      properties:
+        type:
+          type: string
+        id:
+          type: string
+        name:
+          type: ["string", "null"]
+        email:
+          type: ["string", "null"]
+    Attachment:
+      type: object
+      required: [type, name, url, content_type]
+      properties:
+        type:
+          type: string
+        name:
+          type: string
+        url:
+          type: string
+        content_type:
+          type: string
+        filesize:
+          type: integer
+        width:
+          type: ["integer", "null"]
+        height:
+          type: ["integer", "null"]
+    ConversationPart:
+      type: object
+      required: [type, id, part_type, created_at, author]
+      properties:
+        type:
+          type: string
+          enum: [conversation_part]
+        id:
+          type: string
+        part_type:
+          type: string
+        body:
+          type: ["string", "null"]
+        created_at:
+          type: integer
+          x-mockingbird-volatile:
+            kind: timestamp
+        updated_at:
+          type: integer
+          x-mockingbird-volatile:
+            kind: timestamp
+        notified_at:
+          type: integer
+          x-mockingbird-volatile:
+            kind: timestamp
+        assigned_to:
+          type: ["object", "null"]
+        author:
+          $ref: "#/components/schemas/Author"
+        attachments:
+          type: array
+          items:
+            $ref: "#/components/schemas/Attachment"
+        external_id:
+          type: ["string", "null"]
+        redacted:
+          type: boolean
+    Conversation:
+      type: object
+      required: [type, id, created_at, updated_at, open, state, read, source, contacts]
+      properties:
+        type:
+          type: string
+          enum: [conversation]
+        id:
+          type: string
+          x-mockingbird-resource:
+            type: conversation
+            identity: true
+        title:
+          type: ["string", "null"]
+        created_at:
+          type: integer
+          x-mockingbird-volatile:
+            kind: timestamp
+        updated_at:
+          type: integer
+          x-mockingbird-volatile:
+            kind: timestamp
+        waiting_since:
+          type: ["integer", "null"]
+          x-mockingbird-volatile:
+            kind: timestamp
+        snoozed_until:
+          type: ["integer", "null"]
+        open:
+          type: boolean
+        state:
+          type: string
+          enum: [open, closed, snoozed]
+        read:
+          type: boolean
+        priority:
+          type: string
+        admin_assignee_id:
+          type: ["integer", "null"]
+        team_assignee_id:
+          type: ["string", "null"]
+        tags:
+          type: object
+        conversation_rating:
+          type: ["object", "null"]
+        source:
+          type: object
+          required: [type, id, delivered_as, body, author]
+          properties:
+            type:
+              type: string
+            id:
+              type: string
+            delivered_as:
+              type: string
+            subject:
+              type: string
+            body:
+              type: ["string", "null"]
+            author:
+              $ref: "#/components/schemas/Author"
+            attachments:
+              type: array
+              items:
+                $ref: "#/components/schemas/Attachment"
+            url:
+              type: ["string", "null"]
+            redacted:
+              type: boolean
+        contacts:
+          type: object
+          required: [type, contacts]
+          properties:
+            type:
+              type: string
+            contacts:
+              type: array
+              items:
+                type: object
+                required: [type, id]
+                properties:
+                  type:
+                    type: string
+                  id:
+                    type: string
+                  external_id:
+                    type: ["string", "null"]
+        teammates:
+          type: object
+        custom_attributes:
+          type: object
+        first_contact_reply:
+          type: ["object", "null"]
+        sla_applied:
+          type: ["object", "null"]
+        statistics:
+          type: ["object", "null"]
+        ai_agent_participated:
+          type: boolean
+        conversation_parts:
+          type: object
+          required: [type, conversation_parts, total_count]
+          properties:
+            type:
+              type: string
+            conversation_parts:
+              type: array
+              items:
+                $ref: "#/components/schemas/ConversationPart"
+            total_count:
+              type: integer
+    ConversationList:
+      type: object
+      required: [type, pages, total_count, conversations]
+      properties:
+        type:
+          type: string
+          enum: [conversation.list]
+        pages:
+          $ref: "#/components/schemas/Pages"
+        total_count:
+          type: integer
+        conversations:
+          type: array
+          items:
+            $ref: "#/components/schemas/Conversation"
+    Message:
+      type: object
+      required: [type, id, created_at, body, message_type, conversation_id]
+      properties:
+        type:
+          type: string
+          enum: [user_message]
+        id:
+          type: string
+        created_at:
+          type: integer
+          x-mockingbird-volatile:
+            kind: timestamp
+        body:
+          type: string
+        message_type:
+          type: string
+          enum: [inapp]
+        conversation_id:
+          type: string
+          x-mockingbird-resource:
+            type: conversation
+            identity: true
+    Admin:
+      type: object
+      required: [type, id, name, email]
+      properties:
+        type:
+          type: string
+          enum: [admin]
+        id:
+          type: string
+          x-mockingbird-resource:
+            type: admin
+            identity: true
+        name:
+          type: string
+        email:
+          type: string
+        job_title:
+          type: ["string", "null"]
+        away_mode_enabled:
+          type: boolean
+        away_mode_reassign:
+          type: boolean
+        has_inbox_seat:
+          type: boolean
+        team_ids:
+          type: array
+          items:
+            type: integer