Method call_user

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).

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
answer_timeout timeout in seconds to wait for the user to answer the call any positive integer 180 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 user will be called at its terminals (obs: we currentl don't call users at PSTN, set for example by followme).

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:

1
2
3
4

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

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

1
2
3
4

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

Response:

1
2
3
4
5
6
7

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

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

1
2
3
4

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

Response:

1
2
3
4
5
6
7

{
  "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:

1
2
3
4

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

Response:

1
2
3
4
5
6
7

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

Example 4: Failed request due to channel limit

1
2
3
4

curl -u 'DOMAIN_NAME:API_TOKEN' \
    https://bcs.brastel.com/basix/api/call_user \
    -H 'Content-Type: application/json' \
    -d '{"user_extension": "1001", "destination": "0312341234"}'

Response:

1
2
3
4
5
6

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

Example 5: Using callback_url

1
2
3
4

curl -u 'DOMAIN_NAME:API_TOKEN' \
    https://bcs.brastel.com/basix/api/call_user \
    -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"}'

Response:

1
2
3
4
5
6
7

{
  "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.

In case of success:

1
2
3
4

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

In case of error:

1
2
3
4
5
6

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

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

1
2
3
4

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

Response:

1
2
3
4
5
6
7

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