--- title: "Add a participant to a call" method: POST path: "/service_agents/calls/{id}/participants" tags: ["Service Agent"] --- # Add a participant to a call `POST /service_agents/calls/{id}/participants` ## Request - Base URL: `https://api.voipbin.net/v1.0` - URL: `https://api.voipbin.net/v1.0/service_agents/calls/{id}/participants` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Brings a colleague's extension into a call the calling agent owns, turning a two-party call into a three-party call. The colleague's phone rings. When the colleague answers, the colleague joins the call. The other two parties are not put on hold or muted and are not interrupted. The call must be one the calling agent owns, be in progress and be a two-party call. The participant must be an extension of the calling agent's customer. Any other address type, or an extension that does not exist, is deleted or belongs to another customer, is rejected with 400. A call that already has three parties, a call that is not in a conference, an extension that has no registered phone, and a request made while another participant is being added to the same call are rejected with 409. After a participant was added or declined, a new request can be refused for up to 90 seconds. The response is the group call of the new leg. It carries the IDs of the call legs in `call_ids`. The calls themselves can appear a moment after the response, and an extension with several registered phones has one leg per phone, of which only the one that answers joins. The legs belong to the colleague, so they are not returned from `GET /service_agents/calls` of the calling agent. Follow the progress from the call events. When the three-party call ends depends on how the original call started. If the call came in through a queue, it ends when the customer leaves, and it continues when the calling agent leaves. If the calling agent placed the call, it ends for everyone when the calling agent leaves. In both cases the call ends when only one party is left. Calls that reached the agent in another way, for example a direct call to the agent's extension, were not measured. The recording of a leg that was started before continues. Insight listening cannot be started while there are three parties. ## Path parameters - `id` string, uuid, required ## Request body - object - `address` CallManagerParticipantAddress, required: A colleague's extension to bring into a call. Used by `POST /service_agents/transfers` and `POST /service_agents/calls/{id}/participants`. - `type` 'extension', required: Type of address. Only `extension` is accepted. - `target` string, uuid, required: The extension ID of the colleague to reach. It is the `target` of the address of type `extension` returned from the `GET /service_agents/agents` response. The extension must belong to the calling agent's customer. ## Response `200` The group call of the new leg. - 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). - `403`: Insufficient permission (PERMISSION_DENIED). - `404`: Resource not found (NOT_FOUND). - `409`: State conflict (ALREADY_EXISTS or FAILED_PRECONDITION). - `500`: Internal error (INTERNAL). - `503`: Upstream unavailable (UNAVAILABLE). ## Changes - **2026-11-03** `d1c9ff61d99c`: 1 info - endpoint added [Operation history](https://skmtc.dev/voipbin/apis/voipbin-api/changes/service_agents/calls/:id/participants/post.md) --- [API](https://skmtc.dev/voipbin/apis/voipbin-api.md) - [All operations](https://skmtc.dev/voipbin/apis/voipbin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voipbin/apis/voipbin-api/revisions/ae049dcc6c89?raw)