Create a group chat

curl --request POST \
  --url https://osis.co/api/v1/comms/groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "participants": [
    "<string>"
  ],
  "body": "<string>",
  "line_e164": "<string>",
  "line_id": "<string>",
  "name": "<string>",
  "default_country": "<string>",
  "idempotency_key": "<string>"
}
'

import requests

url = "https://osis.co/api/v1/comms/groups"

payload = {
    "participants": ["<string>"],
    "body": "<string>",
    "line_e164": "<string>",
    "line_id": "<string>",
    "name": "<string>",
    "default_country": "<string>",
    "idempotency_key": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    participants: ['<string>'],
    body: JSON.stringify('<string>'),
    line_e164: '<string>',
    line_id: '<string>',
    name: '<string>',
    default_country: '<string>',
    idempotency_key: '<string>'
  })
};

fetch('https://osis.co/api/v1/comms/groups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://osis.co/api/v1/comms/groups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'participants' => [
        '<string>'
    ],
    'body' => '<string>',
    'line_e164' => '<string>',
    'line_id' => '<string>',
    'name' => '<string>',
    'default_country' => '<string>',
    'idempotency_key' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://osis.co/api/v1/comms/groups"

	payload := strings.NewReader("{\n  \"participants\": [\n    \"<string>\"\n  ],\n  \"body\": \"<string>\",\n  \"line_e164\": \"<string>\",\n  \"line_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"default_country\": \"<string>\",\n  \"idempotency_key\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://osis.co/api/v1/comms/groups")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"participants\": [\n    \"<string>\"\n  ],\n  \"body\": \"<string>\",\n  \"line_e164\": \"<string>\",\n  \"line_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"default_country\": \"<string>\",\n  \"idempotency_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://osis.co/api/v1/comms/groups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"participants\": [\n    \"<string>\"\n  ],\n  \"body\": \"<string>\",\n  \"line_e164\": \"<string>\",\n  \"line_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"default_country\": \"<string>\",\n  \"idempotency_key\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

POST

groups

Create a group chat

curl --request POST \
  --url https://osis.co/api/v1/comms/groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "participants": [
    "<string>"
  ],
  "body": "<string>",
  "line_e164": "<string>",
  "line_id": "<string>",
  "name": "<string>",
  "default_country": "<string>",
  "idempotency_key": "<string>"
}
'

import requests

url = "https://osis.co/api/v1/comms/groups"

payload = {
    "participants": ["<string>"],
    "body": "<string>",
    "line_e164": "<string>",
    "line_id": "<string>",
    "name": "<string>",
    "default_country": "<string>",
    "idempotency_key": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    participants: ['<string>'],
    body: JSON.stringify('<string>'),
    line_e164: '<string>',
    line_id: '<string>',
    name: '<string>',
    default_country: '<string>',
    idempotency_key: '<string>'
  })
};

fetch('https://osis.co/api/v1/comms/groups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://osis.co/api/v1/comms/groups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'participants' => [
        '<string>'
    ],
    'body' => '<string>',
    'line_e164' => '<string>',
    'line_id' => '<string>',
    'name' => '<string>',
    'default_country' => '<string>',
    'idempotency_key' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://osis.co/api/v1/comms/groups"

	payload := strings.NewReader("{\n  \"participants\": [\n    \"<string>\"\n  ],\n  \"body\": \"<string>\",\n  \"line_e164\": \"<string>\",\n  \"line_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"default_country\": \"<string>\",\n  \"idempotency_key\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://osis.co/api/v1/comms/groups")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"participants\": [\n    \"<string>\"\n  ],\n  \"body\": \"<string>\",\n  \"line_e164\": \"<string>\",\n  \"line_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"default_country\": \"<string>\",\n  \"idempotency_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://osis.co/api/v1/comms/groups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"participants\": [\n    \"<string>\"\n  ],\n  \"body\": \"<string>\",\n  \"line_e164\": \"<string>\",\n  \"line_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"default_country\": \"<string>\",\n  \"idempotency_key\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

Create an iMessage group chat with two or more phone numbers and send its opening message in the same call. The group is created by sending that message, so body is required. The response returns the new group (a conversation) and the message. Group chats are iMessage-only. They are created from a dedicated line that you own, and only from a line whose bridge advertises the groups capability (see List available lines). An older device without native group support answers 409 group_chats_unsupported before any group or message is written. A shared platform line answers 409 group_requires_dedicated_line. All participants must be reachable over iMessage; the service does not silently substitute separate messages or SMS. Scope: comms_send

Request

curl -X POST "https://osis.co/api/v1/comms/groups" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-crew-2026-09" \
  -d '{
    "line_e164": "+16282646448",
    "participants": ["+12125550147", "+12125550148", "+12125550149"],
    "name": "Launch crew",
    "body": "Welcome aboard. This is the launch group for Tuesday."
  }'

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <COMMS_API_KEY>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	Recommended	Stable key for safe retries. A replay returns the original group and message with `duplicate: true` and never creates a second group.

Body parameters

string[]

required

Two to 31 distinct phone numbers to add to the group. E.164 unless default_country is set. Duplicates are dropped. The line itself is never a participant.

string

required

Opening message, up to 10,000 characters. A group chat cannot exist without it.

string

Your dedicated line that creates the group. Required unless line_id is set or the API key is bound to a line. from is accepted as an alias. A line-bound key can only create groups from its own line; naming another line answers 409 line_mismatch.

string

Provider line id (for example line_se_xxhtvk). Alternative to line_e164.

string

Optional display name for the group. Up to 100 characters.

string

ISO country code used only when participants are given in national format.

string

Same as the Idempotency-Key header.

Response

201 Created

The line created the group and accepted the opening message. message.status is submitted until the line observes the send, then follows the same lifecycle as Send a message and fires the same comms.message.* webhook events.

{
  "group": {
    "id": "conversation_01HZX…",
    "name": "Launch crew",
    "state": "created",
    "channel": "imessage",
    "participants": [
      { "phone": "+12125550147", "contact_id": "ctc_01HZX…" },
      { "phone": "+12125550148", "contact_id": "ctc_01HZY…" },
      { "phone": "+12125550149", "contact_id": "ctc_01HZZ…" }
    ],
    "line_id": "line_se_xxhtvk",
    "line_e164": "+16282646448",
    "provider_group_id": "grp_…",
    "created_at": "2026-09-06T18:04:11.000Z"
  },
  "message": {
    "id": "msg_01HZX…",
    "conversation_id": "conversation_01HZX…",
    "contact_id": "",
    "direction": "outbound",
    "channel": "imessage",
    "body": "Welcome aboard. This is the launch group for Tuesday.",
    "status": "submitted",
    "line_id": "line_se_xxhtvk",
    "line_e164": "+16282646448",
    "created_at": "2026-09-06T18:04:11.000Z"
  }
}

group.state is creating, created, unknown, or failed; an unknown outcome is not confirmation that the group exists. group.id is a conversation id. Pass it as conversation_id to List messages to read the thread.

202 Accepted (outcome unknown)

The request may have reached the line but the outcome is not yet known. The body carries delivery_unknown: true and message.status is unknown. Do not retry with a new key; poll the message instead.

200 OK (duplicate)

The same Idempotency-Key was already used for this exact request. A successful creation returns the original group and message with duplicate: true. An uncertain creation remains HTTP 202 on replay, and a failed creation retains its error status. Reusing the key with a different participant set, opening message, name, or line returns HTTP 409.

Errors

Status	`error` / `code`	Meaning
400	`participants_required`, `too_few_participants`, `too_many_participants`	`participants` is missing, has fewer than two distinct numbers, or more than 31
400	`e164_required`, `invalid_phone_number`	A participant is not a valid phone number (`participant` names it)
400	`participant_is_line`	The creating line was listed as a participant
400	`body_required`, `body_too_long`	The opening message is missing or over 10,000 characters
400	`line_required`	No `line_e164`, `line_id`, or bound line
402	`channel_entitlement_denied`	The workspace has no remaining sending entitlement
403	`line_not_owned`	The line is not assigned to this workspace
409	`group_chats_unsupported`	The line’s bridge does not advertise the `groups` capability. Nothing was created.
409	`group_requires_dedicated_line`	The line is the shared platform line
409	`line_mismatch`	A line-bound key named a different line
409	`contact_opted_out`	A participant has opted out (`participant` names it)
409	`idempotency_key_reused`	The key was used with a different request
4xx/502	`provider_delivery_failed`	The line refused to create the group. `group_id` and `message_id` identify the failed attempt; `provider.code` and `provider.reason` say why.

Core

Messages

Conversations

Lines

Webhooks

AI

Events

Create a group chat

Request

Headers

Body parameters

Response

201 Created

202 Accepted (outcome unknown)

200 OK (duplicate)

Errors

See also

​Request

​Headers

​Body parameters

​Response

​201 Created

​202 Accepted (outcome unknown)

​200 OK (duplicate)

​Errors

​See also

Request

Headers

Body parameters

Response

201 Created

202 Accepted (outcome unknown)

200 OK (duplicate)

Errors

See also