osis-co Conversations API

openapi: 3.2.0
info:
  title: Comms Conversations API
  version: 1.0.0
  description: 'Send and receive texts, place and answer calls, and create payment requests from your Comms workspace. Base URL: `https://osis.co/api/v1/comms`. The Payments API has to be turned on for your workspace first.'
servers:
- url: https://osis.co/api/v1/comms
  description: Production
- url: https://comms.osis.co/api/v1/comms
  description: Comms host alias
security:
- bearerAuth: []
tags:
- name: Conversations
paths:
  /conversations:
    get:
      operationId: listConversations
      summary: List conversations
      description: 'List the conversations on your lines. Agent keys see every line attached to the agent unless you filter. Scope: `comms_read`.'
      parameters:
      - name: line_e164
        in: query
        schema:
          type: string
        description: 'For agent keys: only show conversations on this line.'
      - name: state
        in: query
        schema:
          type: string
          enum:
          - agent
          - needs_human
          - human
          - waiting
          - resolved
          - all
        description: Only show conversations in this state. Use all for every state.
      - name: q
        in: query
        schema:
          type: string
        description: Search by contact name, email, phone, latest message, or group name.
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Conversation list
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
      - Conversations
  /conversations/{conversation_id}/typing:
    post:
      operationId: setConversationTyping
      summary: Set typing indicator
      description: 'Show or hide typing dots in an iMessage, RCS, or WhatsApp (beta) conversation. The line has to support typing and have it turned on. Scope: comms_send.'
      parameters:
      - $ref: '#/components/parameters/ConversationId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TypingRequest'
      responses:
        '200':
          description: Typing updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresenceResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
      - Conversations
  /conversations/{conversation_id}/read:
    post:
      operationId: markConversationRead
      summary: Mark conversation read
      description: 'Mark an iMessage, RCS, or WhatsApp (beta) conversation as read and send a read receipt. The line has to support it. Scope: comms_send.'
      parameters:
      - $ref: '#/components/parameters/ConversationId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadRequest'
      responses:
        '200':
          description: Read receipt sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresenceResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
      - Conversations
  /conversations/{conversation_id}/backdrop:
    post:
      operationId: setConversationBackdrop
      summary: Change an iMessage chat background
      description: Beta. Set an iMessage conversation's background to a photo or gradient, or clear it. Needs a line that supports backdrops, comms_send, and an Idempotency-Key. The recipient needs iOS 26 or another Apple OS that shows backgrounds, and a 202 doesn't mean they see it. Images can be JPEG, PNG, or WebP (not animated), up to 3 MiB, 24 megapixels, and 8192 pixels per side. They're cropped to a 1080×2340 portrait frame, and metadata is removed. To retry, send the exact same request with the same idempotency key.
      parameters:
      - $ref: '#/components/parameters/ConversationId'
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[!-~]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatBackdropRequest'
            example:
              type: gradient
              colors:
              - '#0057FF'
              - '#FF3B00'
      responses:
        '202':
          description: Background change accepted. Comms can't confirm what the recipient sees.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatBackdropResponse'
        '400':
          description: Bad request, or the Idempotency-Key is missing
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Your workspace has no sends left
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The key was reused, your key is tied to a different line, or the conversation doesn't support this
        '413':
          description: Image is over 3 MiB, or the request is over 4 MiB + 4096 bytes
        '429':
          description: Too many requests
        '501':
          description: This line doesn't support backgrounds
        '502':
          description: The change failed, or Comms couldn't confirm it
        '503':
          description: Down for a moment. Retry with the same Idempotency-Key.
      tags:
      - Conversations
components:
  schemas:
    ChatBackdropResponse:
      type: object
      required:
      - conversation_id
      - status
      - operation_id
      - replayed
      - recipient_applied
      properties:
        conversation_id:
          type: string
        status:
          type: string
          enum:
          - submitted
          - unknown
          - processing
        operation_id:
          type:
          - string
          - 'null'
        replayed:
          type: boolean
        recipient_applied:
          type: 'null'
          description: Always null. Comms can't see what the recipient's phone shows.
    ChatBackdropRequest:
      oneOf:
      - type: object
        additionalProperties: false
        required:
        - type
        - colors
        properties:
          type:
            const: gradient
            type: string
          colors:
            type: array
            minItems: 2
            maxItems: 8
            items:
              type: string
              pattern: ^#[0-9A-Fa-f]{6}$
        title: Gradient
      - type: object
        additionalProperties: false
        required:
        - type
        properties:
          type:
            const: clear
            type: string
        title: Clear
      - type: object
        additionalProperties: false
        required:
        - type
        - image_base64
        - content_type
        properties:
          type:
            const: image
            type: string
          image_base64:
            type: string
            format: byte
            minLength: 4
            maxLength: 4194304
            description: 'The image file as plain base64, with no data: prefix. Up to 3 MiB.'
          content_type:
            type: string
            enum:
            - image/jpeg
            - image/png
            - image/webp
          crop:
            type: object
            additionalProperties: false
            required:
            - x
            - y
            - width
            - height
            description: Which part of the image to use, as fractions from 0 to 1, after EXIF rotation. x + width and y + height can't go over 1. Defaults to the whole image.
            properties:
              x:
                type: number
                minimum: 0
                maximum: 1
              y:
                type: number
                minimum: 0
                maximum: 1
              width:
                type: number
                exclusiveMinimum: 0
                maximum: 1
              height:
                type: number
                exclusiveMinimum: 0
                maximum: 1
          position:
            type: object
            additionalProperties: false
            required:
            - x
            - y
            description: 'What stays in view if the image needs trimming to fit the portrait frame: 0 is left or top, 0.5 is center, 1 is right or bottom. Defaults to center.'
            properties:
              x:
                type: number
                minimum: 0
                maximum: 1
                default: 0.5
              y:
                type: number
                minimum: 0
                maximum: 1
                default: 0.5
        title: Image
    ReadRequest:
      type: object
      properties:
        force:
          type: boolean
          default: true
    TypingRequest:
      type: object
      properties:
        active:
          type: boolean
          default: true
    PresenceResponse:
      type: object
      properties:
        ok:
          type: boolean
        active:
          type: boolean
        read:
          type: boolean
        skipped:
          type: boolean
        reason:
          type:
          - string
          - 'null'
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        retry_after:
          type: integer
        reason:
          type: string
    Conversation:
      type: object
      properties:
        id:
          type: string
        contact_id:
          type: string
        phone:
          type: string
          description: The other person's number, in E.164 format.
        name:
          type: string
        channel:
          type: string
        state:
          type: string
        last_message_at:
          type: string
          format: date-time
        last_message_preview:
          type: string
        unread:
          type: boolean
        line_e164:
          type: string
          description: Your number in this conversation. Left out if unknown.
  responses:
    Conflict:
      description: The conversation isn't available, or the request conflicts with an earlier one
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Your key doesn't have the scope this needs
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: API key is missing or wrong
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ConversationId:
      name: conversation_id
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Your API key from the Comms dashboard (`osis_…`).