The method call_user creates a new call in your Basix PBX by calling a specified basix user in your domain and after answer, transferring he/she to a specified destination.

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

Method parameters

Parameter Name Description Allowed Values Default Value Optional
user_id user to call as originating leg a user id none yes
user_name user to call as originating leg a user name none yes
user_label user to call as originating leg a user label none yes
user_extension user to call as originating leg a user extension none yes
user_did user to call as originating leg a user DID none yes
user_email user to call as originating leg a user email 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
callback_url URL to be called informing result of call to user (answered/not-answered) any valid HTTP/HTTPS URL none yes
auto_answer indicates if auto_answer intruction should be sent to SIP terminals that support it true or false false yes
calling_name name/number that should show up in terminals of the originating leg any ascii string none yes
group_id group context of originating leg a group id none yes
group_name group context of originating leg a group name none yes
group_label group context of originating leg a group label none yes
group_extension group context of originating leg a group extension none yes
group_did group context of originating leg a group DID number none yes
group_resolver group context of originating leg currently it can be "*" (any group the user belongs to), or "any:CALL_CENTER" (any CallCenter group the user belongs to) none yes

The user_id, name_name, user_label, user_extension, user_did and user_email are all optional: we just need to provide one of them to identify the user to be called.

The group_id, group_name, group_label, group_extension, group_did and group_resolver are all optional: if we want to mark the originating leg as belonging to a group, we just need to provide one of them to identify the group.

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:

{ "user_id": 1234, "destination": "0377778888" }

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

{ "user_id": 1234, "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.

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 user) 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 the channel that answered the call.

Examples using curl

Example 1: Calling user 10001001 connecting it with 0312341234

$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_user -X POST -H 'Content-Type: application/json' -d '{"user_id": 10001001, "destination": "0312341234"}'

{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96","1c46fc4b-a42f-410e-82b5-11aa2a1f69fe"]}

Example 2: Calling user "jessica" connecting her with user "thomas"

$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_user -X POST -H 'Content-Type: application/json' -d '{"user_name": "jessica", "calling_name": "Thomas Jenkins", destination": "thomas"}'

{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96","1c46fc4b-a42f-410e-82b5-11aa2a1f69fe"]}

Example 3: Calling user "bob" connecting him with PSTN 0312341234 using calling_number 0506868000 and setting end_user identity:

$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_user -X POST -H 'Content-Type: application/json' -d '{"user_name": "bob", "destination": {"called_number": "0312341234", "calling_number": "05068680000", "end_user": {"name": "thomas"}}}'

{"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_user -X POST -H 'Content-Type: application/json' -d '{"user_extension": "1001", "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_user -X POST -H 'Content-Type: application/json' -d '{"user_email": "jones@abcd.com", "destination": "{name=Charles Xavier,organization=X-Men}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.

Example 6: Calling user 'james' with group 'sales' context and connecting it with 0312341234

$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_user -X POST -H 'Content-Type: application/json' -d '{"user_name": "james", "group_name": "sales", "destination": "0312341234"}'

{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96","1c46fc4b-a42f-410e-82b5-11aa2a1f69fe"]}