Method call_external

The method call_external creates a new call in your Basix PBX by calling a specified external address (PSTN number) and after answer, transferring he/she to a specified destination.

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

Parameters

Parameter Name Description Allowed Values Default Value Optional
target external number to call as originating leg any PSTN number. You can specify a calling_number and/or end_user identity: instead of just a string you can pass a complex object with details. none no
answer_timeout timeout in seconds to wait for target to answer the call any positive integer 180 yes
destination destination to which originating leg will be connected to after answer any valid internal destination in your PBX. Obs: PSTN numbers are external destinations and are not valid none no
callback_url URL to be called informing result of call to group (answered/not-answered) any valid HTTP/HTTPS URL none yes

For the parameter target instead of a simple string you can specify an object with additional details. So instead of just this:

1
2
3
4
5

{
  "target": "0311112222",
  "answer_timeout": 30,
  "destination": "group1"
}

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

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

{
  "target": {
    "called_number": "0311112222",
    "calling_number": "0506868001",
    "end_user": {
      "id": "12345678",
      "name": "Olive",
      "organization": "Thimble Theatre",
      "avatar": "https://gravatar/jo9j9sdj93j9j9jw9j39wj39.jpg",
      "prefecture": "Illinois"
    }
  },
  "answer_timeout": 30,
  "destination": "group1"
}

Note that this is just a more detailed format of the target parameter.

It permits to specify a calling_number if desired and details about the end_user at the target.

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 something like "target": "0311112222"

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 containing one Channel UUID (for the leg generated to call the address) 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 if call was successful or not.

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

Examples using curl

Example 1: Calling 0312341234 and connecting whoever answers with group "sales"

1
2
3
4

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

Response:

1
2
3
4
5
6

{
  "result_code": 0,
  "uuids": [
    "ede7b23e-c172-445e-832e-963b11ba2b96"
  ]
}

Example 2: Calling some end_user called "luke.s" at 0312341234 and connecting whoever answers with user "helen"

1
2
3
4

curl -u 'DOMAIN_NAME:API_TOKEN' \
  https://bcs.brastel.com/basix/api/call_external \
  -H 'Content-Type: application/json' \
  -d '{"target": {"end_user": {"name": "luke.s"}, "called_number": "0312341234"}, "destination": "helen"}'

Response:

1
2
3
4
5
6

{
  "result_code": 0,
  "uuids": [
    "ede7b23e-c172-445e-832e-963b11ba2b96"
  ]
}

Example 3: Calling 0901111222 using calling_number 05068601111 connecting whoever answers with group "campaign"

1
2
3
4

curl -u 'DOMAIN_NAME:API_TOKEN' \
  https://bcs.brastel.com/basix/api/call_external \
  -H 'Content-Type: application/json' \
  -d '{"target": {"calling_number": "05068601111", "called_number": "09011112222"}, "destination": "campaign"}'

Response:

1
2
3
4
5
6

{
  "result_code": 0,
  "uuids": [
    "ede7b23e-c172-445e-832e-963b11ba2b96"
  ]
}

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_external \
  -H 'Content-Type: application/json' \
  -d '{"target": "090111122222", "destination": "campaign"}'

Response:

1
2
3
4
5
6

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

Example 5: sending call to XML server via an extension number or DID

1
2
3
4

curl -u 'DOMAIN_NAME:API_TOKEN' \
  https://bcs.brastel.com/basix/api/call_external \
  -H 'Content-Type: application/json' \
  -d '{"target": {"calling_number": "05068601111", "called_number": "09011112222"}, "destination": "1234"}'

Response:

1
2
3
4
5
6

{
  "result_code": 0,
  "uuids": [
    "ede7b23e-c172-445e-832e-963b11ba2b96"
  ]
}

In the above, extension '1234' would be configured to send the call to XML server

Example 6: sending call to a XML server specified in destination (requires your domain to have ON_THE_FLY_IVR_ALLOWED privilege)

1
2
3
4

curl -u 'DOMAIN_NAME:API_TOKEN' \
  https://bcs.brastel.com/basix/api/call_external \
  -H 'Content-Type: application/json' \
  -d '{"target": "09011112222", "destination": "xml_url:https://YOUR_XML_SERVER/fax_ivr"}'

Response:

1
2
3
4
5
6

{
  "result_code": 0,
  "uuids": [
    "ede7b23e-c172-445e-832e-963b11ba2b96"
  ]
}

xml_url: the URL that will provide the XML to process the call (See Basix XML)

Example 7: Using callback_url

1
2
3
4

curl -u 'DOMAIN_NAME:API_TOKEN' \
    https://bcs.brastel.com/basix/api/call_external \
    -H 'Content-Type: application/json' \
    -d '{"target": "09011112222", "destination": "sales", "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 8: Using inline_xml

This is for the case you just want to create an outgoing call ivr without having to prepare a xml server or upload a xml file to your domain storage.

You need to encode the IVR XML definition using base64 and passing it as an url of with schema inline_xml://

Ex:

1
2
3
4
5
6
7

$ echo "<IVR><Play>some_msg.wav</Play></IVR>" | base64
PElWUj48UGxheT5zb21lX21zZy53YXY8L1BsYXk+PElWUj4K

$ curl -u 'DOMAIN_NAME:API_TOKEN' \
    https://bcs.brastel.com/basix/api/call_external \
    -H 'Content-Type: application/json' \
    -d '{"target": "09011112222", "destination": "xml_url:inline_xml://PElWUj48UGxheT5zb21lX21zZy53YXY8L1BsYXk+PElWUj4K"}'