Per gli agenti AI: markdown di questa pagina — /docs-content-en/telephony-users.md indice della documentazione — /llms.txt

Gli articoli della documentazione sono attualmente disponibili solo in inglese.

Employee telephony settings

GET /v1/telephony-users

Returns employee telephony settings: the default outbound line, SIP phone status, the server address and login for connecting the SIP phone, and the extension number. The SIP password is never returned. The hasPassword flag is returned instead.

Scope: telephony. Works only with an OAuth application key vibe_app_… and a user session token. Bitrix24 checks permission to read the settings and may require administrator approval.

Parameters

Parameter Type Req. Description
ParameteruserIds (query) Typestring Req.yes DescriptionComma-separated positive employee IDs. List: GET /v1/users

Examples

A personal key vibe_api_… receives 403 OAUTH_REQUIRED. Use an OAuth application key vibe_app_….

curl — OAuth application

Terminal 
curl -X GET 'https://vibecode.bitrix24.com/v1/telephony-users?userIds=42,43' \
  -H 'X-Api-Key: YOUR_APP_KEY' \
  -H 'Authorization: Bearer USER_SESSION_TOKEN'

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/telephony-users?userIds=42,43', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
console.log(data)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionTelephony settings for each employee found
Fielddata[].id Typestring DescriptionEmployee ID
Fielddata[].defaultLine Typestring DescriptionDefault outbound line
Fielddata[].phoneEnabled Typestring DescriptionWhether the SIP phone is activated: Y — yes, N — no
Fielddata[].sipServer Typestring DescriptionServer address for connecting the SIP phone
Fielddata[].sipLogin Typestring DescriptionLogin for connecting the SIP phone
Fielddata[].hasPassword Typeboolean DescriptionWhether a SIP password is set. The password itself is not returned
Fielddata[].innerNumber Typestring DescriptionEmployee extension number

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": "77",
      "hasPassword": true,
      "innerNumber": "177"
    }
  ]
}

Error response example

403 — request with a personal key:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_REQUIRED",
    "message": "This endpoint requires an OAuth application key; webhook keys have no application context."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionuserIds is missing or contains a value that is not a positive integer
HTTP403 CodeOAUTH_REQUIRED DescriptionRequest with a personal key vibe_api_…. An OAuth application key is required
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the telephony scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access to the telephony settings
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe key was not found or has been revoked
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no connection to Bitrix24
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in message
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned an invalid response
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

Full list of common API errors — Errors.

See also