Para agentes de IA: markdown de esta página — /docs-content-en/voximplant-sip/update.md índice de la documentación — /llms.txt

Los artículos de la documentación están disponibles actualmente en 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
configId (path) number yes Connection ID. List: GET /v1/voximplant-sip

Request fields (body)

Field Type Required Description
title string no New connection name
server string no New SIP server address
login string no New login on the SIP server
password string no New password. It is not returned in responses — the hasPassword flag is returned instead
type string no Current 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
success boolean true on success
data.configId string Connection ID
data.type string PBX type: office — office PBX, cloud — cloud PBX
data.title string Connection name
data.server string SIP server address
data.login string Login on the SIP server
data.hasPassword boolean Whether the connection password is set
data.authUser string | null User name for authentication on the SIP server. null if not set
data.outboundProxy string | null Proxy server address for outgoing calls. null if not set
data.detectLineNumber string Whether to detect the line number from the SIP headers of an incoming call: N — do not detect
data.lineDetectHeaderOrder string SIP headers used to detect the line number, in the order they are checked, for example diversion;to
data.registrationStatusCode string | null Result code of registration on the SIP server, for example 502 when the server is not found
data.registrationErrorMessage string | null Registration error text. null if there is no error
data.regId string Cloud PBX only: registration ID on the SIP server
data.incomingServer string Office PBX only: server address for incoming calls, issued by Bitrix24
data.incomingLogin string Office PBX only: login for incoming calls, issued by Bitrix24
data.hasIncomingPassword boolean Office 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
400 INVALID_PARAMS The request body is not a JSON object
400 INVALID_PARAMS The body has no field to change other than type: the body is empty or contains only type
400 INVALID_PARAMS type is neither office nor cloud
400 INVALID_PARAMS A field value is not a string
400 INVALID_PARAMS configId is not a positive integer
400 READONLY_FIELD type differs from the current connection type
400 READONLY_FIELD The body contains a field other than type, title, server, login, password
404 ENTITY_NOT_FOUND There is no connection with this configId among the connections available to the key
422 BITRIX_ERROR Bitrix24 did not confirm the update; the message is Bitrix24 did not confirm the update
422 BITRIX_ERROR Bitrix24 rejected the update; the reason is in error.message
401 MISSING_API_KEY The X-Api-Key header was not sent
401 INVALID_API_KEY The platform does not recognize the key string: a typo, a truncated value or a deleted key
401 TOKEN_MISSING The 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
403 SCOPE_DENIED The key does not have the telephony scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — see access rights
403 BITRIX_ACCESS_DENIED Bitrix24 denied access — causes explained
429 RATE_LIMITED Request rate exceeded
429 QUEUE_OVERFLOW The account request queue is full, so the request is rejected without waiting. The Retry-After header suggests the delay
429 QUEUE_TIMEOUT The request did not get through the account queue in time and was not sent to Bitrix24. The Retry-After header suggests the delay
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable
503 BITRIX_TIMEOUT Bitrix24 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