> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getdial.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server. # Create a group POST https://api.getdial.ai/api/v1/groups Content-Type: application/json Creates a new WhatsApp group from one of your lines, with the people you name in it. The line that creates the group is its admin. **The group is ready to use as soon as this returns.** Dial records it before responding, so its `id` works as `groupId` on Send a message straight away, and it appears in List groups. There is no event for a group you created — the response is the confirmation. **Not everyone you name is always added.** WhatsApp lets people choose who may add them to groups, so a participant can be refused while the group is still created with everyone else. Those participants come back in `notAdded` and are not in the group; `reason: "privacy_restricted"` means their settings only allow their contacts to add them. Dial does not retry them or send them an invite. The group gets WhatsApp's ordinary new-group settings: every member may send messages and edit the group's info. One group per request; there is no description, picture, or invite link. **A `504` does not mean the group wasn't created.** When the line doesn't confirm the group in time, the group may still exist. Check List groups before trying again — a blind retry can create a duplicate group. Reference: https://docs.getdial.ai/api-reference/rest-api/groups/create-group ## Authentication - `Authorization` header (bearer token, required) — Your Dial API key, sent as `Authorization: Bearer sk_live_...` ## Request ### Body (application/json) This endpoint expects an object. - `name` (string, required) — The group's name (its subject), as members see it. - `participants` (list of string, required) — The people to add, as E.164 numbers. Duplicates are ignored. The creating line's own number is rejected with `400` — the line is in the group already, as its admin. - `fromNumber` (string, optional) — The line that creates the group, in E.164 format, or its nickname. It becomes the group's admin. Provide at most one of `fromNumber` or `fromNumberId`; with neither, your primary number creates the group. - `fromNumberId` (string, optional) — ID of the Dial number that creates the group (see List phone numbers). Alternative to `fromNumber` — provide at most one of the two. ## Response ### 201 Group created. - `group` (Group, optional) — A group conversation — a conversation that is not a phone number, and so has an ID of its own. Address it with `groupId` when sending, and filter for it on List messages. Groups exist on WhatsApp lines and iMessage numbers. - `notAdded` (list of ApiV1GroupsPostResponsesContentApplicationJsonSchemaNotAddedItems, optional) — Participants who were not added, and so are not in the group. Empty when everyone was added. ## Errors ### 400 Bad Request Error The request failed validation — a missing or invalid `name` or `participants`, both `fromNumber` and `fromNumberId`, or the line's own number among `participants` — or the number can't create groups ("This number can't create groups."): it isn't a WhatsApp-ready line. - `error` (ErrorError, optional) — An error message, or a validation-error object for 400 responses. ### 401 Unauthorized Error Missing or invalid API key. - `error` (ErrorError, optional) — An error message, or a validation-error object for 400 responses. ### 404 Not Found Error The requested resource was not found on this account. - `error` (ErrorError, optional) — An error message, or a validation-error object for 400 responses. ### 429 Too Many Requests Error "This line has created too many groups recently. Try again later." WhatsApp is limiting how often this line can create groups; nothing was created. - `error` (ErrorError, optional) — An error message, or a validation-error object for 400 responses. ### 502 Bad Gateway Error "WhatsApp refused to create the group." Nothing was created; retrying the same request is unlikely to succeed. - `error` (ErrorError, optional) — An error message, or a validation-error object for 400 responses. ### 504 Gateway Timeout Error "The group wasn't confirmed in time. Check List groups before trying again." The group may exist — check List groups before retrying, or you may create a duplicate. - `error` (ErrorError, optional) — An error message, or a validation-error object for 400 responses. ## Types ### Group A group conversation — a conversation that is not a phone number, and so has an ID of its own. Address it with `groupId` when sending, and filter for it on List messages. Groups exist on WhatsApp lines and iMessage numbers. - `id` (string, required) — The group's Dial ID. Never the channel's own group identifier, which is opaque, unroutable, and does not cross this boundary. - `channel` (enum, required) — The channel the group is on — the same value as `channel` on its messages. A group never changes channel, so a send into it needs no `channel`; naming a different one is rejected with `400`. - Allowed values: `whatsapp`, `imessage` - `name` (string, required, nullable) — The group's current name, or null when no line could report it. Not stored: participants rename groups, so a saved subject would be a cache with nothing to invalidate it. It is read live from the line holding the conversation, and a line that cannot answer in time yields null here rather than failing the whole listing. - `createdAt` (datetime, required) — When Dial first learned of this group — your line creating it or being added to it, or the first message that named it. Not when the group itself was created, except for a group your line created. ### ApiV1GroupsPostResponsesContentApplicationJsonSchemaNotAddedItems - `number` (string, optional, nullable) — The participant's E.164 number, or null only when the line could not say which participant it was. - `reason` (enum, optional) — `privacy_restricted` — the participant's settings only allow their contacts to add them to groups. `not_added` — WhatsApp did not add them for another reason. - Allowed values: `privacy_restricted`, `not_added` ### ErrorError An error message, or a validation-error object for 400 responses. - string - map from string to any ## Examples **Request** ```json { "name": "Kickoff planning", "participants": [ "+14155550123", "+14155550124" ] } ``` **Response** ```json { "group": { "id": "grp_123", "channel": "whatsapp", "name": "Planning bday party", "createdAt": "2024-01-15T09:30:00Z" }, "notAdded": [ { "number": "+14155550124", "reason": "privacy_restricted" } ] } ``` **SDK Code** ```python import requests url = "https://api.getdial.ai/api/v1/groups" payload = { "name": "Kickoff planning", "participants": ["+14155550123", "+14155550124"] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.getdial.ai/api/v1/groups'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"Kickoff planning","participants":["+14155550123","+14155550124"]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.getdial.ai/api/v1/groups" payload := strings.NewReader("{\n \"name\": \"Kickoff planning\",\n \"participants\": [\n \"+14155550123\",\n \"+14155550124\"\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.getdial.ai/api/v1/groups") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Kickoff planning\",\n \"participants\": [\n \"+14155550123\",\n \"+14155550124\"\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.getdial.ai/api/v1/groups") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"Kickoff planning\",\n \"participants\": [\n \"+14155550123\",\n \"+14155550124\"\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.getdial.ai/api/v1/groups', [ 'body' => '{ "name": "Kickoff planning", "participants": [ "+14155550123", "+14155550124" ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.getdial.ai/api/v1/groups"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Kickoff planning\",\n \"participants\": [\n \"+14155550123\",\n \"+14155550124\"\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "Kickoff planning", "participants": ["+14155550123", "+14155550124"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.getdial.ai/api/v1/groups")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```