osis-co Groups API

openapi: 3.2.0
info:
  title: Comms Groups 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: Groups
paths:
  /groups:
    post:
      operationId: createGroupChat
      summary: Create a group chat
      description: 'Start an iMessage or WhatsApp (beta) group chat from your dedicated line and send the first message. For iMessage groups, everyone needs iMessage. Lines without group support return 409 group_chats_unsupported. Shared lines return 409 group_requires_dedicated_line. Scope: comms_send.'
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: 'Lets you retry safely. A retry returns the first group and message with duplicate: true.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupChatRequest'
            example:
              participants:
              - '+12125550147'
              - '+12125550148'
              line_e164: '+12025550101'
              body: Welcome to the group!
      responses:
        '201':
          description: Group created and first message accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGroupChatResponse'
        '202':
          description: 'The request may have gone through, but the result isn''t known yet (delivery_unknown: true)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGroupChatResponse'
        '200':
          description: 'You already sent this request. Returns the first group and message with duplicate: true. If the first result was unknown you get 202 again, and if it failed you get the same error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGroupChatResponse'
        '400':
          description: 'Bad request: participants_required, e164_required, invalid_phone_number, too_few_participants, too_many_participants, participant_is_line, body_required, body_too_long, invalid_group_name, line_required'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: 'Can''t do it: group_chats_unsupported, group_requires_dedicated_line, line_mismatch, line_channel_unsupported, contact_opted_out, idempotency_key_reused'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Groups
components:
  schemas:
    InboundAttachment:
      type: object
      required:
      - filename
      - content_type
      - mediaType
      properties:
        id:
          type: string
        filename:
          type: string
        content_type:
          type: string
        mediaType:
          type: string
        size_bytes:
          type: integer
          minimum: 0
        transcription:
          type: string
        url:
          type: string
          format: uri
          description: Where to download the file. Needs an API key with comms_read from the same workspace and line.
    CreateGroupChatResponse:
      type: object
      properties:
        group:
          $ref: '#/components/schemas/GroupChat'
        message:
          $ref: '#/components/schemas/Message'
        duplicate:
          type: boolean
        delivery_unknown:
          type: boolean
    GroupChat:
      type: object
      properties:
        id:
          type: string
          description: The group's conversation ID. Use it as conversation_id to read or send messages.
        name:
          type:
          - string
          - 'null'
        channel:
          type: string
          enum:
          - imessage
          - whatsapp
        participants:
          type: array
          items:
            type: object
            properties:
              phone:
                type: string
              contact_id:
                type: string
        line_id:
          type: string
        line_e164:
          type:
          - string
          - 'null'
        provider_group_id:
          type: string
          description: Another ID for the group. For API requests, use id as the conversation_id.
        created_at:
          type: string
          format: date-time
        state:
          type: string
          enum:
          - creating
          - created
          - unknown
          - failed
          description: Whether the group was created. If it's unknown, don't assume the group exists.
    CreateGroupChatRequest:
      type: object
      required:
      - participants
      - body
      properties:
        participants:
          type: array
          minItems: 2
          maxItems: 31
          items:
            type: string
          description: 2 to 31 different phone numbers. Use E.164 unless you set default_country. Don't include your own line.
          examples:
          - - '+12125550147'
            - '+12125550148'
        body:
          type: string
          description: The first message. Required, because sending it is what creates the group.
          examples:
          - Welcome to the launch crew.
          minLength: 1
          maxLength: 10000
        name:
          type: string
          maxLength: 100
          description: A name for the group.
        line_e164:
          type: string
          description: The dedicated line that starts the group. You can also call it from. Required unless you set line_id or your key is tied to a line.
          examples:
          - '+12025550101'
        line_id:
          type: string
          description: The line's ID. Use this instead of line_e164 if you like.
        from:
          type: string
          description: Another name for line_e164.
        default_country:
          type: string
          description: Country code, only needed if participants are local numbers without a country code.
        idempotency_key:
          type: string
          description: Same as the Idempotency-Key header.
        channel:
          type: string
          enum:
          - imessage
          - whatsapp
          description: imessage (default) or whatsapp.
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        retry_after:
          type: integer
        reason:
          type: string
    Message:
      type: object
      properties:
        id:
          type: string
        body:
          type: string
        direction:
          type: string
          enum:
          - outbound
          - inbound
        conversation_id:
          type: string
        reply_to_message_id:
          type: string
          description: The ID of the message this replies to, if it's in this conversation.
        thread_root_message_id:
          type: string
          description: The first message in this thread.
        channel:
          type: string
          enum:
          - sms
          - imessage
          - rcs
          - whatsapp
        status:
          type: string
        contact_id:
          type: string
        line_id:
          type: string
          description: Line ID when available.
        line_e164:
          type: string
          description: 'Your number in this conversation: the number that received the message, or the number you sent from.'
        to:
          type: string
        read_at:
          type: string
          format: date-time
          description: The native read time when a read receipt is available. For one-to-one iMessage and RCS, the recipient must have read receipts on. Never available for SMS; absence does not mean unread.
        created_at:
          type: string
          format: date-time
        audience:
          type: string
          enum:
          - direct
          - shared
          description: Whether the message is in a group conversation or a one-on-one conversation.
        author:
          type: object
          description: Who sent the message. Display names aren't verified.
          properties:
            contact_id:
              type: string
            external_id:
              type: string
            display_name:
              type: string
          required:
          - contact_id
          - external_id
        reply_to_provider_message_id:
          type: string
          description: Another ID for the message this replies to, when available.
        thread_originator_guid:
          type: string
          description: Another ID for the first message in the thread, when available.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/InboundAttachment'
          description: Files someone sent you. If a message is only files, body is empty.
        unsent_at:
          type: string
          format: date-time
          description: When the unsend was confirmed. The original text and delivery history are kept.
  responses:
    PaymentRequired:
      description: You've used your plan's messages
      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'
    RateLimited:
      description: Too many requests. Slow down and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: API key is missing or wrong
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Your API key from the Comms dashboard (`osis_…`).