Control a phone call

POST/api/v1/domains/{domain_uuid}/phone-control/actions

Send a supported action to a registered phone. First find the phone with the targets endpoint and check its supported_actions. Answer, end, transfer, hold and resume actions require a call in the expected state. Set dry_run to true to preview an action without sending it.

This request can start a call or change a phone’s current call state.

Path parameters

domain_uuidstringrequired

Your company ID supplied by Junction Cloud Connections. Use the same ID throughout your requests.

Request body application/json

extensionstringrequired

Extension number to control.

actionstringrequired

Action to execute. Valid values: hold, resume, blind-transfer, attended-transfer, complete-transfer, cancel-transfer, conference, mute-toggle, mute-on, mute-off, end-call, answer-call, dnd-on, dnd-off, or dnd-toggle.

destinationstring

Optional. Required for blind-transfer and attended-transfer.

agentstring

Optional. Preferred selector for a specific phone. Use an agent value from the targets response; plain text matching is case-insensitive.

vendorstring

Optional. Broader selector for a supported driver: yealink, snom, poly, polycom, ringotel, grandstream, or generic.

lan_ipstring

Optional. Exact device IP selector from the targets response.

call_idstring

Optional. Registration call ID selector from a target's registration_call_ids.

no_resumeboolean

Optional. For cancel-transfer, leave the original call held. Default: false.

dry_runboolean

Optional. Preview the command without sending it. Default: false.

Responses

200Dry run

objectstring

actionstring

dry_runboolean

sentboolean

resultsarray[object]

Show nested fields

sentboolean

vendorstring

400Validation error

errorobject

Show nested fields

typestring

messagestring

codestring

paramstring

401Unauthenticated

errorobject

Show nested fields

typestring

messagestring

codestring

403The request is not available for this account.

404Extension not found

errorobject

Show nested fields

typestring

messagestring

codestring

paramstring

409Invalid call state

errorobject

Show nested fields

typestring

messagestring

codestring

paramstring

500Internal server error

errorobject

Show nested fields

typestring

messagestring

REQUEST EXAMPLE

Replace the host, token and example IDs with your account details.

curl --request POST \
  --url "https://YOUR-PORTAL-HOST/api/v1/domains/YOUR_COMPANY_UUID/phone-control/actions" \
  --header "Authorization: Bearer $JUNCTIONCC_API_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
  "extension": "1001",
  "action": "hold",
  "agent": "SIP-T53W",
  "dry_run": true
}'

const token = process.env.JUNCTIONCC_API_TOKEN;

const response = await fetch("https://YOUR-PORTAL-HOST/api/v1/domains/YOUR_COMPANY_UUID/phone-control/actions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "extension": "1001",
  "action": "hold",
  "agent": "SIP-T53W",
  "dry_run": true
})
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const text = await response.text();
console.log(text ? JSON.parse(text) : null);

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://YOUR-PORTAL-HOST/api/v1/domains/YOUR_COMPANY_UUID/phone-control/actions",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["JUNCTIONCC_API_TOKEN"],
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data=json.dumps({'extension': '1001', 'action': 'hold', 'agent': 'SIP-T53W', 'dry_run': True}).encode("utf-8")
)
with urlopen(request, timeout=30) as response:
    body = response.read()
    print(json.loads(body) if body else None)

RESPONSE EXAMPLE

{
  "object": "phone_control_action",
  "action": "hold",
  "dry_run": true,
  "sent": true,
  "results": [
    {
      "sent": true,
      "vendor": "yealink"
    }
  ]
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "The destination field is required when action is blind transfer.",
    "code": "invalid_parameter",
    "param": "destination"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "Unauthenticated.",
    "code": "unauthenticated"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "Extension not found.",
    "code": "resource_missing",
    "param": "extension"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "The call on 1001@pbx.example.com is already on hold.",
    "code": "invalid_call_state",
    "param": "action"
  }
}

{
  "error": {
    "type": "api_error",
    "message": "An unexpected error occurred."
  }
}