The method call_group creates a new call in your Basix PBX by calling a specified basix group in your domain and after answer, transferring the call to a specified destination.

It will create a channel (originating leg) by calling a group. Then, when the channel gets answered it will be connected to any destination reachable by the PBX (destination can be another PSTN number, a user, a group, an extension number, etc).

Method parameters

Parameter Name Description Allowed Values Default Value Optional
group_id group to call as originating leg a group id none yes
group_name group to call as originating leg a group name none yes
group_label group to call as originating leg a group label none yes
group_extension group to call as originating leg a group extension none yes
group_did group to call as originating leg a group DID none yes
destination destination to which originating leg will be connected to after answer any valid destination in your PBX. If destination is a PSTN number, you can specify a calling_number and/or end_user identity. none no
answer_timeout for how long to wait for the call to the group to be answered number of seconds the group's answer_timeout yes
member_answer_timeout for how long to wait for the call to a group member to answer the call number of seconds the group's member_answer_timeout yes
calling_name name/number that should show up in terminals of the originating leg any ascii string none yes
callback_url URL to be called informing result of call to group (answered/not-answered) any valid HTTP/HTTPS URL none yes

The group_id, group_name, group_label, group_extension and group_did are all optional: we just need to provide one of them to identify the group to be called.

In case destination is a PSTN number: instead of a simple string you can specify an object with additional details. So instead of just this:

{ "group_id": 1111, "destination": "0377778888" }

we can use something like this (adding optional parameters):

{ "group_id": 1111, "destination": { "called_number": "0377778888", "calling_number": "0506868002", "end_user": { "id": 11223344, "name": "Popeye", "organization": "Thimble Theatre", "avatar": "https://gravatar/3osdj93j9jw3j9j93w939w5.jpg" } } }

Note that this is just a more detailed format of the destination parameter. You don't have to use all of sub-parameters shown. You just add the ones you need. If you don't need anything then just use "destination": "0377778888"

The end_user information will be relayed in WebSocket CTI notifications so it can be rendered by web apps.

Currently we call the group members using hunting (calling members one by one). Allowing to call using ringing method will be added in a future release.


Response will return a json string with result_code=0 in case of success and a list of Channel UUIDs (one for each originating leg generated to call the group members) A non-zero result_code indicates an error and will be accompanied by a description of the error.

result_code Description
0 Success
500 Error. Details will be present in the json string.


When the hunt finishes, if specified, the callback_url will be called informing the call UUID of the group member that answered the call:

Parameter Name Description
result_code see above
uuid uuid of channel that answered the call.

Examples using curl

Example 1: Calling group "support" with answer_timeout set to 10 seconds and connecting whoever answers with 0312341234

$ curl -u 'DOMAIN_NAME:API_TOKEN' -X POST -H 'Content-Type: application/json' -d '{"group_name": "support", "answer_timeout": 10, "destination": "0312341234"}'


Example 2: Calling group with extension "1111" connecting whoever answers with user "erik"

$ curl -u 'DOMAIN_NAME:API_TOKEN' -X POST -H 'Content-Type: application/json' -d '{"group_extension": "1111", "calling_name": "Erik Lehnsherr", "destination": "erik"}'


Example 3: Calling group with extension "1111" connecting whoever answers with PSTN 0312341234 using calling_number 05068680000 and setting end_user identity

$ curl -u 'DOMAIN_NAME:API_TOKEN' -X POST -H 'Content-Type: application/json' -d '{"group_extension": "1111", "destination": {"called_number": "0312341234", "calling_number": "05068680000", "end_user": {"id": "#1234", "name": "Tim Tyler"}}}'


Example 4: Failed request due to channel limit

$ curl -u 'DOMAIN_NAME:API_TOKEN' -X POST -H 'Content-Type: application/json' -d '{"group_id": 10001111, "destination": "0312341234"}'


Example 5: Using callback_url

$ curl -u 'DOMAIN_NAME:API_TOKEN' -X POST -H 'Content-Type: application/json' -d '{"group_extension": "1111", "destination": "{name=James Hudson}0312341234", "callback_url": ""}'


After the attempt to call the user finishes, an HTTP POST to https:/ will be made with JSON:

{ "result_code": 0, "uuid": "ONE_OF_THE_UUIDS_MENTIONED_IN_THE_METHOD_REPLY" }

in case of success or

{ "result_code": 500, "error": { "id": "SOME_ERROR_ID" } }

in case of error.