Para agentes de IA: markdown desta página — /docs-content-en/voximplant-sip/get.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Get connection

GET /v1/voximplant-sip/:configId

Returns an office or cloud PBX SIP connection by ID — for example, to check the registration on the SIP server after creating the connection.

Parameters

Parameter Type Required Description
ParameterconfigId (path) Typenumber Requiredyes DescriptionConnection ID. List: GET /v1/voximplant-sip

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/voximplant-sip/17" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/voximplant-sip/17" \
  -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/voximplant-sip/17', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
if (success) {
  console.log(data.title, data.server, 'password set:', data.hasPassword)
}

JavaScript — OAuth application

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

const { success, data } = await res.json()
if (success) {
  console.log(data.title, data.server, 'password set:', data.hasPassword)
}

Response fields

Passwords are not returned — the response carries the hasPassword and hasIncomingPassword flags instead.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe SIP connection. Its fields are the data.* rows below
Fielddata.configId Typestring DescriptionConnection ID
Fielddata.type Typestring DescriptionPBX type: office — office PBX, cloud — cloud PBX
Fielddata.title Typestring DescriptionConnection name
Fielddata.server Typestring DescriptionSIP server address
Fielddata.login Typestring DescriptionLogin on the SIP server
Fielddata.hasPassword Typeboolean DescriptionWhether the connection password is set
Fielddata.authUser Typestring | null DescriptionUser name for authorization on the SIP server. null if not set
Fielddata.outboundProxy Typestring | null DescriptionProxy server address for outgoing calls. null if not set
Fielddata.detectLineNumber Typestring DescriptionWhether to detect the line number from the SIP headers of an incoming call: N — do not detect
Fielddata.lineDetectHeaderOrder Typestring DescriptionSIP headers used to detect the line number, in the order they are checked, for example diversion;to
Fielddata.registrationStatusCode Typestring | null DescriptionResult code of the registration on the SIP server, for example 502 when the server is not found
Fielddata.registrationErrorMessage Typestring | null DescriptionRegistration error text. null if there is no error
Fielddata.regId Typestring DescriptionCloud PBX only: registration ID on the SIP server
Fielddata.incomingServer Typestring DescriptionOffice PBX only: server address for incoming calls, issued by Bitrix24
Fielddata.incomingLogin Typestring DescriptionOffice PBX only: login for incoming calls, issued by Bitrix24
Fielddata.hasIncomingPassword Typeboolean DescriptionOffice PBX only: whether the password for incoming calls is set

Response example

JSON 
{
  "success": true,
  "data": {
    "type": "office",
    "configId": "17",
    "server": "sip.example.com",
    "login": "office-line",
    "hasPassword": true,
    "incomingServer": "ip.b24-1234-1234567890.bitrixphone.com",
    "incomingLogin": "sip17",
    "hasIncomingPassword": true,
    "authUser": null,
    "outboundProxy": null,
    "detectLineNumber": "N",
    "lineDetectHeaderOrder": "diversion;to",
    "registrationStatusCode": "0",
    "registrationErrorMessage": null,
    "title": "Office PBX"
  }
}

Error response example

404 — connection not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "SIP connection not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionconfigId is not a positive integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo connection with this configId among the connections available to the key
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe platform does not know this key string: a typo, a truncated value or a deleted key
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no access to the portal: a personal key has no portal webhook, or an application key was sent without a session token in Authorization: Bearer
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the telephony scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access — causes explained
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in error.message
HTTP429 CodeRATE_LIMITED DescriptionRequest rate limit exceeded
HTTP429 CodeQUEUE_OVERFLOW DescriptionThe account request queue is full, so the request is rejected without waiting. The Retry-After header suggests the delay
HTTP429 CodeQUEUE_TIMEOUT DescriptionThe request did not get through the account queue in time and was not sent to Bitrix24. The Retry-After header suggests the delay
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

Full list of common API errors — Errors.

Known specifics

  • Only connections of the key's own application are visible. The method finds a connection only if it was created by the same Bitrix24 application as the key: an application key sees the connections of its own application, a personal key sees the connections created through the Bitrix24 account's webhooks. For the configId of another application's connection, the method responds with 404 ENTITY_NOT_FOUND.

See also