لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/telephony/lines.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Lines

Create, update, and delete an application's external lines, plus read the list of lines rented from Voximplant or connected over SIP.

Bitrix24 API: telephony.externalLine.*, voximplant.line.get Scope: telephony

List application lines

GET /v1/telephony-lines

Returns the list of external lines added by the application via POST /v1/telephony-lines. The list is returned in full — filtering, sorting, and offset are not supported and are rejected with 400. Pick the line you need on the client side.

Parameters

Parameter Type Default Description
Parameterselect (query) Typestring Default— DescriptionField selection in camelCase: ?select=number,name
Parameterlimit (query) Typenumber Default50 DescriptionNumber of records (up to 5000)
ParameterwithTotal (query) Typestring Default— DescriptionThe values true and false are recognized. For application lines the parameter does not affect the response: meta.total is returned even with withTotal=false

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/telephony-lines" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/telephony-lines" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/telephony-lines', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} lines`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/telephony-lines', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of lines. Empty until the application adds a line via POST /v1/telephony-lines
Fielddata[].number Typestring DescriptionLine identifier set at creation
Fielddata[].name Typestring | null DescriptionDisplay name. null if not set at creation
Fielddata[].crmAutoCreate Typeboolean DescriptionAuto-create a CRM entity on an outbound call through this line: true — create, false — do not create
Fieldmeta.total Typenumber DescriptionTotal number of application lines
Fieldmeta.hasMore Typeboolean DescriptionWhether more records exist beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "number": "sip-line-1",
      "name": "Main line",
      "crmAutoCreate": true
    },
    {
      "number": "sip-line-2",
      "name": "Support line",
      "crmAutoCreate": false
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'telephony' scope"
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNSUPPORTED_FILTER DescriptionA filter was passed — filtering by line fields is not supported
HTTP400 CodeINVALID_SORT_FIELD DescriptionA sort or order was passed — sorting is not supported
HTTP400 CodeUNSUPPORTED_OFFSET DescriptionA non-zero offset was passed — application lines do not support pagination
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is inactive or revoked
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the telephony scope
HTTP429 CodeRATE_LIMITED DescriptionRequest rate limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

Only this application's lines. The list contains lines created via POST /v1/telephony-lines under the current API key. Lines rented from Voximplant or connected over SIP are available via GET /v1/voximplant-lines.

serverName is not returned. The field is declared in the field schema but never comes back in the list under any condition — even if it was set at creation (details).

See also