Create a Group Chat
curl --request POST \
--url https://app.tuco.ai/api/unibox/create-group \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/unibox/create-group"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/unibox/create-group', 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://app.tuco.ai/api/unibox/create-group",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/unibox/create-group"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.tuco.ai/api/unibox/create-group")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/unibox/create-group")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyMessages
Create a Group Chat
Start a new iMessage group chat from one of your Tuco lines: pick the people, optionally name it, and send the first message. Bearer-token auth, JSON.
POST
/
api
/
unibox
/
create-group
Create a Group Chat
curl --request POST \
--url https://app.tuco.ai/api/unibox/create-group \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/unibox/create-group"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/unibox/create-group', 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://app.tuco.ai/api/unibox/create-group",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/unibox/create-group"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.tuco.ai/api/unibox/create-group")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/unibox/create-group")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyWhat this endpoint does
It starts a new iMessage group from one of your lines and sends the first message into it. In iMessage a group is created by sending its first message, somessage is required.
After that the group works like any other group your line is in:
- send into it with Send to a Group Chat
- it shows in the Unibox and in List Conversations
- members’ replies come back as
group.message.*webhooks
Everyone must be on iMessage. Tuco checks each person before anything is sent. If anyone
isn’t on iMessage, nothing is sent and you get
MEMBER_NOT_IMESSAGE with their number.
Groups never fall back to SMS.Authentication
Pass your workspace API key as a Bearer token.Authorization: Bearer tuco_xxxxxxxxxxxxx
Request body
| Field | Type | Required | What it is |
|---|---|---|---|
members | string[] | Yes | 2 to 31 people: phone numbers in E.164 (+13025550100) or email addresses (Apple IDs). Duplicates and your own line are removed. |
message | string | Yes | The first message, up to 5,000 characters, text only. Send files after with Send to a Group Chat. |
name | string | No | The group’s name, up to 100 characters. Shown on everyone’s phone. |
lineId | string | Only if you have more than one line | Which line starts the group. Get ids from List Lines. The line needs group-chat support (every Tuco-hosted line has it). |
idempotencyKey | string | No | Recommended. A retry with the same key gets the first result back instead of starting a second group. Also accepted as the Idempotency-Key header. |
Example
curl -X POST "https://app.tuco.ai/api/unibox/create-group" \
-H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: q4-deal-room-1" \
-d '{
"lineId": "6a42688ad3aeb6d18286686c",
"members": ["+13025550100", "sam@example.com"],
"name": "Q4 Deal Room",
"message": "Hi both, starting a thread for the Q4 deal."
}'
const res = await fetch('https://app.tuco.ai/api/unibox/create-group', {
method: 'POST',
headers: {
Authorization: 'Bearer tuco_xxxxxxxxxxxxx',
'Content-Type': 'application/json',
'Idempotency-Key': 'q4-deal-room-1',
},
body: JSON.stringify({
lineId: '6a42688ad3aeb6d18286686c',
members: ['+13025550100', 'sam@example.com'],
name: 'Q4 Deal Room',
message: 'Hi both, starting a thread for the Q4 deal.',
}),
});
const data = await res.json();
// data.conversationId → use it with /api/unibox/send-group
import requests
res = requests.post(
"https://app.tuco.ai/api/unibox/create-group",
headers={
"Authorization": "Bearer tuco_xxxxxxxxxxxxx",
"Idempotency-Key": "q4-deal-room-1",
},
json={
"lineId": "6a42688ad3aeb6d18286686c",
"members": ["+13025550100", "sam@example.com"],
"name": "Q4 Deal Room",
"message": "Hi both, starting a thread for the Q4 deal.",
},
)
print(res.json()["conversationId"])
Response
200
{
"success": true,
"conversationId": "group:iMessage;+;chat52247337719921698",
"chatGuid": "iMessage;+;chat52247337719921698",
"messageId": "6b00b219fb16ed81dc80d3e7",
"members": ["+13025550100", "sam@example.com"],
"newConversationsCounted": 2,
"existingGroup": false,
"name": "Q4 Deal Room",
"nameApplied": true
}
| Field | What it means |
|---|---|
conversationId | The group’s id. Use it with Send to a Group Chat and in the Unibox. When you put it in a URL (?conversation=), URL-encode it: the + must be %2B. |
newConversationsCounted | How many of the line’s daily new-conversation slots this used (see below). |
existingGroup | true when these exact people already had a group with this line. iMessage reuses that group instead of making a second one (same as on an iPhone), and your message went into it. Add or remove someone to start a new group. |
nameApplied | Only when you sent name. false means the group was created but the name didn’t apply; nameError says why. Nothing else is affected. |
Daily limits
A group counts against your line’s new conversations per day limit:- each person this line has never messaged (1:1 or in a group) uses 1 slot
- people the line has messaged before use none
- the first message counts as 1 message toward the daily message limit
LINE_NEW_CONVERSATION_LIMIT.
Example, a group of you + 2 people: both never messaged → 2 slots; one messaged before → 1 slot.
Errors
Nothing is sent on any of these unless the table says otherwise.| HTTP | code | What happened | What to do |
|---|---|---|---|
| 400 | MESSAGE_REQUIRED | No first message. | Add message: the group is created by sending it. |
| 400 | MESSAGE_TOO_LONG | Over 5,000 characters. | Shorten it. |
| 400 | TOO_FEW_MEMBERS | Fewer than 2 other people (after removing duplicates and your own line). | For one person, send a normal message instead. |
| 400 | TOO_MANY_MEMBERS | More than 31 people. | Use fewer people. |
| 400 | INVALID_MEMBER | A member isn’t a phone number or an email. | Fix the entries listed in invalid. |
| 400 | MEMBER_NOT_IMESSAGE | These people aren’t on iMessage (listed in members). | Remove them, or text them 1:1. |
| 503 | MEMBER_CHECK_FAILED | The iMessage check didn’t answer for these people. | Try again in a minute. |
| 400 | NAME_TOO_LONG / INVALID_NAME | name is over 100 characters or isn’t text. | Fix name. |
| 400 | LINE_ID_REQUIRED | You have more than one line and didn’t pass lineId. | Pass lineId (some of your lines are listed in lines). |
| 404 | LINE_NOT_FOUND | That line isn’t in your workspace. | Check lineId. |
| 409 | LINE_NOT_READY / NO_USABLE_LINE | The line is paused, its device is down, or it can’t create groups. | Use another line, or check the line on the Lines page. |
| 429 | LINE_NEW_CONVERSATION_LIMIT | Not enough new-conversation room left today (slotsLeft, newMembers). | Use fewer new people, another line, or try tomorrow. |
| 502 | CREATE_FAILED | The device refused to create the group. Nothing was sent and no slots were used. | Check the line is up, then try again. |
| 504 | CREATE_UNCONFIRMED | The device didn’t answer in time. The group may still have been created. | Don’t retry with a new key. Check the Unibox in a few minutes; a retry with the same idempotency key gets the group once it’s confirmed. |
Webhooks and CRM
- The first message fires
group.message.sent, exactly once. - If your workspace has a CRM connected, the message is logged on each member’s contact, and a contact is created for anyone the CRM doesn’t have. See Group chats in your CRM.
What you can’t do
| Add or remove members, or rename later | Not from Tuco yet. Anyone in the group can do it from their phone. |
| Start a group from a line without group-chat support | Pick another line. |
| Two groups with exactly the same people on one line | iMessage reuses the existing group (existingGroup: true). |