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 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 |
|---|---|---|---|---|
| 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 (user, group, extension number etc.) in your PBX. Obs: PSTN numbers and Basix DIDs (Phone number assigned to Basix Customers) are not valid. | none | no |
For the parameter target instead of a simple string you can specify an object with additional details. So instead of just this:
{ "target": "0311112222", "answer_timeout": 30, "destination": "group1" }
we can use something like this (adding optional parameters):
{ "target": { "called_number": "0311112222", "calling_number": "0506868001", "end_user": { "id": 12345678, "name": "Olive", "organization": "Thimble Theatre", "avatar": "https://gravatar/jo9j9sdj93j9j9jw9j39wj39.jpg" } }, "answer_timeout": 30, "destination": "sales" }
![https://gravatar/jo9j9sdj93j9j9jw9j39wj39.jpg"](https://gravatar/jo9j9sdj93j9j9jw9j39wj39.jpg"){kind=link}
Note that this is just a more detailed format of the target 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 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"
$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_external -X POST -H 'Content-Type: application/json' -d '{"target": "0312341234", "destination": "sales"}'
{"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"
$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_external -X POST -H 'Content-Type: application/json' -d '{"target": {"end_user": {"name": "luke.s"}, "called_number": "0312341234"}, "destination": "helen"}'
{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96"]}
Example 3: Calling 0901111222 using calling_number 05068601111 connecting whoever answers with group "campaign"
$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_external -X POST -H 'Content-Type: application/json' -d '{"target": {"calling_number": "05068601111", "called_number": "09011112222"}, "destination": "campaign"}'
{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96"]}
Example 4: Failed request due to channel limit
$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_external -X POST -H 'Content-Type: application/json' -d '{"target": "090111122222", "destination": "campaign"}'
{"result_code":500,"error":{"id":"channel_limit_reached"}}
Example 5: Calling 0312341234 and connecting with plivo "plivo1" which Extension number is 1001
$ curl -u 'DOMAIN_NAME:API_TOKEN' https://bcs.brastel.com/basix/api/call_external -X POST -H 'Content-Type: application/json' -d '{"target": "0312341234", "destination": "1001"}'
{"result_code":0,"uuids":["ede7b23e-c172-445e-832e-963b11ba2b96"]}