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

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

Update connection

PATCH /v1/voximplant-sip/:configId

Changes the name, SIP server address, login or password of a SIP connection. The body is a flat JSON object with only the fields to change.

Parameters

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

Request fields (body)

Field Type Required Description
Fieldtitle Typestring Requiredno DescriptionNew connection name
Fieldserver Typestring Requiredno DescriptionNew SIP server address
Fieldlogin Typestring Requiredno DescriptionNew login on the SIP server
Fieldpassword Typestring Requiredno DescriptionNew password. It is not returned in responses — the hasPassword flag is returned instead
Fieldtype Typestring Requiredno DescriptionCurrent connection type: office or cloud. A different type is not accepted — the type cannot be changed after creation

Pass at least one field other than type. Fields missing from the body stay unchanged. All values are strings; the body accepts no other fields.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/voximplant-sip/17" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Office PBX, second floor"}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/voximplant-sip/17" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Office PBX, second floor"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/voximplant-sip/17', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Office PBX, second floor' }),
})

const { success, data } = await res.json()
if (success) {
  console.log('New name:', data.title)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/voximplant-sip/17', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Office PBX, second floor' }),
})

const { success, data } = await res.json()
if (success) {
  console.log('New name:', data.title)
}

Response fields

The response contains the whole connection with the changes already applied. Passwords are not included in the response — the hasPassword and hasIncomingPassword flags are returned instead.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
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 authentication 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 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, second floor"
  }
}

Error response example

400 — an attempt to change the connection type:

JSON 
{
  "success": false,
  "error": {
    "code": "READONLY_FIELD",
    "message": "Connection type cannot be changed"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object
HTTP400 CodeINVALID_PARAMS DescriptionThe body has no field to change other than type: the body is empty or contains only type
HTTP400 CodeINVALID_PARAMS Descriptiontype is neither office nor cloud
HTTP400 CodeINVALID_PARAMS DescriptionA field value is not a string
HTTP400 CodeINVALID_PARAMS DescriptionconfigId is not a positive integer
HTTP400 CodeREADONLY_FIELD Descriptiontype differs from the current connection type
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a field other than type, title, server, login, password
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no connection with this configId among the connections available to the key
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not confirm the update; the message is Bitrix24 did not confirm the update
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the update; the reason is in error.message
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not sent
HTTP401 CodeINVALID_API_KEY DescriptionThe platform does not recognize the 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 app key was sent without a session token in Authorization: Bearer
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the telephony scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access — causes explained
HTTP429 CodeRATE_LIMITED DescriptionRequest rate 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 a connection of your own application can be updated. The method finds a connection only if it was created by the same Bitrix24 application as the key: an app key sees the connections of its own application, a personal key sees connections created through Bitrix24 account webhooks. For the configId of another application's connection, the method responds with 404 ENTITY_NOT_FOUND.

See also