---
title: "Create a group chat"
method: POST
path: "/groups"
---

# Create a group chat

`POST /groups`

## Request

- Base URL: `https://osis.co/api/v1/comms`
- URL: `https://osis.co/api/v1/comms/groups`
- Auth: HTTP bearer

Start an iMessage group chat from your dedicated line and send the first message. Everyone in the group needs iMessage. Lines without group support return 409 group_chats_unsupported. Shared lines return 409 group_requires_dedicated_line. Scope: comms_send.

## Headers

- `Idempotency-Key` string

## Request body

- CreateGroupChatRequest
  - `participants` string[], required: 2 to 31 different phone numbers. Use E.164 unless you set default_country. Don't include your own line.
  - `body` string, required: The first message. Required, because sending it is what creates the group.
  - `name` string: A name for the group.
  - `line_e164` string: 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.
  - `line_id` string: The line's ID. Use this instead of line_e164 if you like.
  - `from` string: Another name for line_e164.
  - `default_country` string: Country code, only needed if participants are local numbers without a country code.
  - `idempotency_key` string: Same as the Idempotency-Key header.
  - `channel` 'imessage' | 'whatsapp': imessage (default) or whatsapp.

## Response `200`

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.

- CreateGroupChatResponse
  - `group` GroupChat
    - `id` string: The group's conversation ID. Use it as conversation_id to read or send messages.
    - `name` string, nullable
    - `channel` 'imessage' | 'whatsapp'
    - `participants` object[]
      - `phone` string
      - `contact_id` string
    - `line_id` string
    - `line_e164` string, nullable
    - `provider_group_id` string: Another ID for the group. For API requests, use id as the conversation_id.
    - `created_at` string, date-time
    - `state` 'creating' | 'created' | 'unknown' | 'failed': Whether the group was created. If it's unknown, don't assume the group exists.
  - `message` Message
    - `id` string
    - `body` string
    - `direction` 'outbound' | 'inbound'
    - `conversation_id` string
    - `reply_to_message_id` string: The ID of the message this replies to, if it's in this conversation.
    - `thread_root_message_id` string: The first message in this thread.
    - `channel` 'sms' | 'imessage' | 'rcs' | 'whatsapp'
    - `status` string
    - `contact_id` string
    - `line_id` string: Line ID when available.
    - `line_e164` string: Your number in this conversation: the number that received the message, or the number you sent from.
    - `to` string
    - `read_at` string, date-time: 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` string, date-time
    - `audience` 'direct' | 'shared': Whether the message is in a group conversation or a one-on-one conversation.
    - `author` object: Who sent the message. Display names aren't verified.
      - `contact_id` string, required
      - `external_id` string, required
      - `display_name` string
    - `reply_to_provider_message_id` string: Another ID for the message this replies to, when available.
    - `thread_originator_guid` string: Another ID for the first message in the thread, when available.
    - `attachments` InboundAttachment[]: Files someone sent you. If a message is only files, body is empty.
      - `id` string
      - `filename` string, required
      - `content_type` string, required
      - `mediaType` string, required
      - `size_bytes` integer
      - `transcription` string
      - `url` string, uri: Where to download the file. Needs an API key with comms_read from the same workspace and line.
    - `unsent_at` string, date-time: When the unsend was confirmed. The original text and delivery history are kept.
  - `duplicate` boolean
  - `delivery_unknown` boolean

## Other responses

- `201`: Group created and first message accepted
- `202`: The request may have gone through, but the result isn't known yet (delivery_unknown: true)
- `400`: 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
- `401`: API key is missing or wrong
- `402`: You've used your plan's messages
- `403`: Your key doesn't have the scope this needs
- `409`: Can't do it: group_chats_unsupported, group_requires_dedicated_line, line_mismatch, line_channel_unsupported, contact_opted_out, idempotency_key_reused
- `429`: Too many requests. Slow down and retry.

---

[API](https://skmtc.dev/osis/apis/comms-api.md) · [All operations](https://skmtc.dev/osis/apis/comms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/osis/apis/comms-api/revisions/59a4c0ba8936?raw)