---
title: "Create a new groupcall"
method: POST
path: "/groupcalls"
tags: ["Groupcall"]
---

# Create a new groupcall

`POST /groupcalls`

Creates a new groupcall with the specified information and returns the created groupcall.

## Request body

- object — Provide either flow_id or actions. If both are set, flow_id takes precedence and actions is ignored.
  - `source` CommonAddress, required — Contains source or destination detail info.
    - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session' — Type of address.
    - `target` string — The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
    - `target_name` string — Address's name.
    - `name` string — Optional label for this address.
    - `detail` string — Additional notes about this address.
  - `destinations` CommonAddress[], required
    - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session' — Type of address.
    - `target` string — The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
    - `target_name` string — Address's name.
    - `name` string — Optional label for this address.
    - `detail` string — Additional notes about this address.
  - `flow_id` string, uuid — The flow to execute for the groupcall. Provide either flow_id or actions; if both are set, flow_id takes precedence and actions is ignored. The flow ID returned from the POST /flows or GET /flows response.
  - `actions` FlowManagerAction[] — Inline actions used to build a temporary flow when flow_id is not provided. Provide either flow_id or actions.
    - `id` string, uuid, required — The unique identifier of this action within the flow.
    - `next_id` string, uuid — The identifier of the next action to execute. References an action `id` within the same flow's `actions` array. Null if this is the last action.
    - `type` 'ai_talk' | 'ai_summary' | 'amd' | 'answer' | 'beep' | 'branch' | 'call' | 'condition_call_digits' | 'condition_call_status' | 'condition_datetime' | 'condition_variable' | 'confbridge_join' | 'conference_join' | 'connect' | 'conversation_send' | 'digits_receive' | 'digits_send' | 'echo' | 'email_send' | 'external_media_start' | 'external_media_stop' | 'fetch' | 'fetch_flow' | 'goto' | 'hangup' | 'message_send' | 'mute' | 'play' | 'queue_join' | 'recording_start' | 'recording_stop' | 'sleep' | 'stop' | 'stream_echo' | 'talk' | 'transcribe_start' | 'transcribe_stop' | 'transcribe_recording' | 'variable_set' | 'webhook_send', required — Type of the action.
    - `option` object — Additional options based on the `type` field. - For `FlowManagerActionTypeAISummary`: see `FlowManagerActionOptionAISummary` - For `FlowManagerActionTypeAITalk`: see `FlowManagerActionOptionAITalk` - For `FlowManagerActionTypeAMD`: see `FlowManagerActionOptionAMD` - For `FlowManagerActionTypeAnswer`: see FlowManagerActionOptionAnswer - For `FlowManagerActionTypeBeep`: see FlowManagerActionOptionBeep - For `FlowManagerActionTypeBranch`: see FlowManagerActionOptionBranch - For `FlowManagerActionTypeCall`: see FlowManagerActionOptionCall - For `FlowManagerActionTypeConfbridgeJoin`: see FlowManagerActionOptionConfbridgeJoin - For `FlowManagerActionTypeConferenceJoin`: see FlowManagerActionOptionConferenceJoin - For `FlowManagerActionTypeConnect`: see FlowManagerActionOptionConnect - For `FlowManagerActionTypeConversationSend`: see FlowManagerActionOptionConversationSend - For `FlowManagerActionTypeDigitsReceive`: see FlowManagerActionOptionDigitsReceive - For `FlowManagerActionTypeDigitsSend`: see FlowManagerActionOptionDigitsSend - For `FlowManagerActionTypeEcho`: see FlowManagerActionOptionEcho - For `FlowManagerActionTypeEmailSend`: see FlowManagerActionOptionEmailSend - For `FlowManagerActionTypeExternalMediaStart`: see FlowManagerActionOptionExternalMediaStart - For `FlowManagerActionTypeExternalMediaStop`: see FlowManagerActionOptionExternalMediaStop - For `FlowManagerActionTypeFetch`: see FlowManagerActionOptionFetch - For `FlowManagerActionTypeFetchFlow`: see FlowManagerActionOptionFetchFlow - For `FlowManagerActionTypeGoto`: see FlowManagerActionOptionGoto - For `FlowManagerActionTypeHangup`: see FlowManagerActionOptionHangup - For `FlowManagerActionTypeMessageSend`: see FlowManagerActionOptionMessageSend - For `FlowManagerActionTypePlay`: see FlowManagerActionOptionPlay - For `FlowManagerActionTypeQueueJoin`: see FlowManagerActionOptionQueueJoin - For `FlowManagerActionTypeRecordingStart`: see FlowManagerActionOptionRecordingStart - For `FlowManagerActionTypeRecordingStop`: see FlowManagerActionOptionRecordingStop - For `FlowManagerActionTypeSleep`: see FlowManagerActionOptionSleep - For `FlowManagerActionTypeStreamEcho`: see FlowManagerActionOptionStreamEcho - For `FlowManagerActionTypeTalk`: see FlowManagerActionOptionTalk - For `FlowManagerActionTypeTranscribeStart`: see FlowManagerActionOptionTranscribeStart - For `FlowManagerActionTypeTranscribeStop`: see FlowManagerActionOptionTranscribeStop - For `FlowManagerActionTypeTranscribeRecording`: see FlowManagerActionOptionTranscribeRecording - For `FlowManagerActionTypeVariableSet`: see FlowManagerActionOptionVariableSet - For `FlowManagerActionTypeWebhookSend`: see FlowManagerActionOptionWebhookSend - ...
    - `tm_execute` string, date-time — Timestamp when this action was executed.
  - `ring_method` '' | 'ring_all' | 'linear', required — Method used for dialing
  - `answer_method` '' | 'hangup_others', required — Method to handle answered calls

## Response `200`

The created groupcall details.

- CallManagerGroupcall — Call or group call information
  - `id` string, uuid — The unique identifier of the group call.
  - `customer_id` string, uuid — The customer ID that owns this group call. Returned from the `GET /customers` response.
  - `owner_type` string — Type of the resource owner (e.g., agent, queue).
  - `owner_id` string, uuid — The unique identifier of the resource owner. Returned from the corresponding owner resource endpoint (e.g., `GET /agents`, `GET /queues`).
  - `status` 'progressing' | 'hangingup' | 'hangup' — Current status of the call or group call
  - `flow_id` string, uuid — The flow ID associated with this group call. Returned from the `POST /flows` or `GET /flows` response.
  - `source` CommonAddress — Contains source or destination detail info.
    - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session' — Type of address.
    - `target` string — The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
    - `target_name` string — Address's name.
    - `name` string — Optional label for this address.
    - `detail` string — Additional notes about this address.
  - `destinations` CommonAddress[] — List of target addresses. Must contain at least one destination.
    - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session' — Type of address.
    - `target` string — The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
    - `target_name` string — Address's name.
    - `name` string — Optional label for this address.
    - `detail` string — Additional notes about this address.
  - `master_call_id` string, uuid, nullable — The unique identifier of the master call that initiated this group call. Returned from the `POST /calls` or `GET /calls` response.
  - `master_groupcall_id` string, uuid, nullable — The unique identifier of the master group call, if applicable. Returned from the `POST /groupcalls` or `GET /groupcalls` response.
  - `ring_method` '' | 'ring_all' | 'linear' — Method used for dialing
  - `answer_method` '' | 'hangup_others' — Method to handle answered calls
  - `answer_call_id` string, uuid — The unique identifier of the answered call. Returned from the `POST /calls` or `GET /calls` response.
  - `call_ids` string[] — List of associated call IDs. Each ID is returned from the `POST /calls` or `GET /calls` response.
  - `answer_groupcall_id` string, uuid — The unique identifier of the answered group call. Returned from the `POST /groupcalls` or `GET /groupcalls` response.
  - `groupcall_ids` string[] — List of associated group call IDs. Each ID is returned from the `POST /groupcalls` or `GET /groupcalls` response.
  - `call_count` integer — Number of remaining calls in the current dial.
  - `groupcall_count` integer — Number of remaining group calls in the current dial.
  - `dial_index` integer, nullable — Current dial index, valid only when the ring method is "ring_all".
  - `tm_create` string, date-time — The creation timestamp.
  - `tm_update` string, date-time — The last update timestamp.
  - `tm_delete` string, date-time, nullable — The deletion timestamp, if applicable.

## Other responses

- `400` — Invalid request (INVALID_ARGUMENT).
- `401` — Authentication required (UNAUTHENTICATED).
- `402` — Payment required (PAYMENT_REQUIRED).
- `500` — Internal error (INTERNAL).
- `503` — Upstream unavailable (UNAVAILABLE).

---

[API](https://skmtc.net/voipbin/apis/voipbin-api.md) · [All operations](https://skmtc.net/voipbin/apis/voipbin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voipbin/voipbin-api/versions/79e779080bcc/schema)