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

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

Create connection

POST /v1/voximplant-sip

Creates a SIP connection to an office or cloud PBX. The Bitrix24 account receives and makes calls through this connection. The body is a flat JSON object.

Request fields (body)

Field Type Required Description
Fieldserver Typestring Requiredyes DescriptionSIP server address
Fieldlogin Typestring Requiredyes DescriptionLogin on the SIP server
Fieldpassword Typestring Requiredno DescriptionConnection password. Not returned in responses — the hasPassword flag is returned instead
Fieldtype Typestring Requiredno DescriptionPBX type: office — office PBX, cloud — cloud PBX. Defaults to cloud. The type cannot be changed after creation
Fieldtitle Typestring Requiredno DescriptionConnection name

All values are strings. The body accepts no other fields.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/voximplant-sip" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "office",
    "title": "Office PBX",
    "server": "sip.example.com",
    "login": "office-line",
    "password": "EXAMPLE_SIP_PASSWORD"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/voximplant-sip" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "office",
    "title": "Office PBX",
    "server": "sip.example.com",
    "login": "office-line",
    "password": "EXAMPLE_SIP_PASSWORD"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/voximplant-sip', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'office',
    title: 'Office PBX',
    server: 'sip.example.com',
    login: 'office-line',
    password: 'EXAMPLE_SIP_PASSWORD',
  }),
})

const { success, data } = await res.json()
if (success) {
  console.log('Created connection', data.configId, 'incoming server:', data.incomingServer)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/voximplant-sip', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'office',
    title: 'Office PBX',
    server: 'sip.example.com',
    login: 'office-line',
    password: 'EXAMPLE_SIP_PASSWORD',
  }),
})

const { success, data } = await res.json()
if (success) {
  console.log('Created connection', data.configId, 'incoming server:', data.incomingServer)
}

Response fields

A successful request returns status 201. Passwords are not included in the response — the hasPassword and hasIncomingPassword flags are returned instead.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.id Typestring DescriptionID of the created connection, same as configId
Fielddata.configId Typestring DescriptionConnection ID — used to get, update, and delete the connection
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. null right after creation
Fielddata.registrationErrorMessage Typestring | null DescriptionRegistration error text. null if there is no error
Fielddata.regId Typenumber DescriptionCloud PBX only: registration ID on the SIP server. A number in the create response, a string in the list and get responses
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": {
    "id": "17",
    "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": null,
    "registrationErrorMessage": null,
    "title": "Office PBX"
  }
}

Error response example

400 — server or login is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "server and login are required"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionserver or login is missing
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object
HTTP400 CodeINVALID_PARAMS Descriptiontype is neither office nor cloud
HTTP400 CodeINVALID_PARAMS DescriptionA field value is not a string
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a field other than type, title, server, login, password
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe platform does not recognize 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 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access — possible causes
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the creation; the reason is in error.message
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

  • Bitrix24 issues the incoming-call credentials for an office PBX. When you create a connection of type office, the response immediately contains incomingServer and incomingLogin, and hasIncomingPassword is true. The API does not return the incoming-call password itself.
  • A connection is visible only to its own application. Only keys of the same Bitrix24 application can find the created connection: a connection created with a personal key is not visible to an app key, and vice versa.

See also