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" } } }
![https://gravatar/3osdj93j9jw3j9j93w939w5.jpg"](https://gravatar/3osdj93j9jw3j9j93w939w5.jpg"){kind=link}
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
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. |
callback_url
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' https://bcs.brastel.com/basix/api/call_group -X POST -H 'Content-Type: application/json' -d '{"group_name": "support", "answer_timeout": 10, "destination": "0312341234"}'
{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96","1c46fc4b-a42f-410e-82b5-11aa2a1f69fe"]}
Example 2: Calling group with extension "1111" connecting whoever answers with user "erik"
$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_group -X POST -H 'Content-Type: application/json' -d '{"group_extension": "1111", "calling_name": "Erik Lehnsherr", "destination": "erik"}'
{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96","1c46fc4b-a42f-410e-82b5-11aa2a1f69fe"]}
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' https://bcs.brastel.com/basix/api/call_group -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"}}}'
{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96","1c46fc4b-a42f-410e-82b5-11aa2a1f69fe"]}
Example 4: Failed request due to channel limit
$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_group -X POST -H 'Content-Type: application/json' -d '{"group_id": 10001111, "destination": "0312341234"}'
{"result_code":500,"error":{"id":"channel_limit_reached"}}
Example 5: Using callback_url
$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_group -X POST -H 'Content-Type: application/json' -d '{"group_extension": "1111", "destination": "{name=James Hudson}0312341234", "callback_url": "https://somewhere.com/result_receiver"}'
{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96","1c46fc4b-a42f-410e-82b5-11aa2a1f69fe"]}
After the attempt to call the user finishes, an HTTP POST to https:/somewhere.com/result_receiver 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.