Create SIP Line voximplant.sip.add

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Scope: telephony

Who can execute the method: user with the Management of numbers — modification access permission

The method voximplant.sip.add creates a new SIP line associated with an application.

Method Parameters

Required parameters are marked with *

Name
type

Description

SERVER*
string

Address of the SIP registration server

LOGIN*
string

Login for connecting to the server

PASSWORD
string

Password for connecting to the server. Maximum length — 100 characters.

Not required for calling the method, but necessary for working registration with the operator

TYPE
string

Type of PBX.

Possible values:

  • cloud - cloud PBX
  • office - office PBX

Default: cloud

TITLE
string

Name of the connection.

If the parameter is not provided, the interface will display a system name based on the connection type:

  • for cloud — Cloud PBX (ID)
  • for office — Office PBX (ID)

where ID is the internal identifier of the SIP line record.

The TITLE field in the method response will be empty in this case

You can connect no more than 10 cloud SIP lines. Exceeding this limit will return the error MAX_CLOUD_PBX

Code Examples

How to Use Examples in Documentation

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"TYPE":"cloud","TITLE":"SIP line 1","SERVER":"sip.provider.com","LOGIN":"sip_user","PASSWORD":"secret"}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/voximplant.sip.add
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"TYPE":"cloud","TITLE":"SIP line 1","SERVER":"sip.provider.com","LOGIN":"sip_user","PASSWORD":"secret","auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/voximplant.sip.add
        
// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of the payload returned in result (match the "response handling" section of the page)
        type SipAddResult = {
          ID: string
          TYPE: string
          CONFIG_ID: string
          REG_ID?: number
          TITLE: string
          SERVER: string
          LOGIN: string
          PASSWORD: string
          AUTH_USER: string | null
          OUTBOUND_PROXY: string | null
          DETECT_LINE_NUMBER: string
          LINE_DETECT_HEADER_ORDER: string
          REGISTRATION_STATUS_CODE: number | null
          REGISTRATION_ERROR_MESSAGE: string | null
          INCOMING_SERVER?: string
          INCOMING_LOGIN?: string
          INCOMING_PASSWORD?: string
        }
        
        try {
          const response = await $b24.actions.v2.call.make<SipAddResult>({
            method: 'voximplant.sip.add',
            params: {
              TYPE: 'cloud',
              TITLE: 'SIP line 1',
              SERVER: 'sip.provider.com',
              LOGIN: 'sip_user',
              PASSWORD: 'secret',
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Created SIP line:', result.ID, result.TYPE, result.TITLE)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function addSipLine() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'voximplant.sip.add',
                params: {
                  TYPE: 'cloud',
                  TITLE: 'SIP line 1',
                  SERVER: 'sip.provider.com',
                  LOGIN: 'sip_user',
                  PASSWORD: 'secret',
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Created SIP line:', result.ID, result.TYPE, result.TITLE)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', addSipLine)
        </script>
        
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.voximplant.sip.add(
                type='cloud',
                title='SIP line 1',
                server='sip.provider.com',
                login='sip_user',
                password='secret',
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'voximplant.sip.add',
                    [
                        'TYPE' => 'cloud',
                        'TITLE' => 'SIP line 1',
                        'SERVER' => 'sip.provider.com',
                        'LOGIN' => 'sip_user',
                        'PASSWORD' => 'secret',
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'voximplant.sip.add',
            {
                TYPE: 'cloud',
                TITLE: 'SIP line 1',
                SERVER: 'sip.provider.com',
                LOGIN: 'sip_user',
                PASSWORD: 'secret'
            },
            function(result)
            {
                if (result.error())
                {
                    console.error(result.error(), result.error_description());
                }
                else
                {
                    console.log(result.data());
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'voximplant.sip.add',
            [
                'TYPE' => 'cloud',
                'TITLE' => 'SIP line 1',
                'SERVER' => 'sip.provider.com',
                'LOGIN' => 'sip_user',
                'PASSWORD' => 'secret',
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        
// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "voximplant.sip.add", b24.Params{
        	"TYPE":     "cloud",
        	"TITLE":    "SIP line 1",
        	"SERVER":   "sip.provider.com",
        	"LOGIN":    "sip_user",
        	"PASSWORD": "secret",
        })
        if err != nil {
        	return fmt.Errorf("voximplant.sip.add: %w", err)
        }
        
        var item struct {
        	ID       b24.ID `json:"ID"`
        	Type     string `json:"TYPE"`
        	ConfigID b24.ID `json:"CONFIG_ID"`
        	RegID    b24.ID `json:"REG_ID"`
        	Title    string `json:"TITLE"`
        	Server   string `json:"SERVER"`
        }
        if err := json.Unmarshal(res.Result, &item); err != nil {
        	return fmt.Errorf("parse response: %w", err)
        }
        fmt.Println(item.ID, item.Type)
        

Response Handling

HTTP Status: 200

Example Response for Creating a Cloud PBX

{
            "result": {
                "ID": "5",
                "TYPE": "cloud",
                "CONFIG_ID": "5",
                "REG_ID": 151082,
                "TITLE": "SIP line 1",
                "SERVER": "sip.provider.com",
                "LOGIN": "sip_user",
                "PASSWORD": "secret",
                "AUTH_USER": null,
                "OUTBOUND_PROXY": null,
                "DETECT_LINE_NUMBER": "N",
                "LINE_DETECT_HEADER_ORDER": "diversion;to",
                "REGISTRATION_STATUS_CODE": null,
                "REGISTRATION_ERROR_MESSAGE": null
            },
            "time": {
                "start": 1773654128,
                "finish": 1773654129.048472,
                "duration": 1.0484719276428223,
                "processing": 1,
                "date_start": "2026-03-16T12:42:08+02:00",
                "date_finish": "2026-03-16T12:42:09+02:00",
                "operating_reset_at": 1773654728,
                "operating": 0.2883341312408447
            }
        }
        

Example Response for Creating an Office PBX

{
            "result": {
                "ID": "7",
                "TYPE": "office",
                "CONFIG_ID": "7",
                "SERVER": "office.provider.local",
                "LOGIN": "office_user",
                "PASSWORD": "secret",
                "INCOMING_SERVER": "ip.b24-6058-1587535982.bitrixphone.com",
                "INCOMING_LOGIN": "sip7",
                "INCOMING_PASSWORD": "71747503265fb091223eb31776a4a225",
                "AUTH_USER": null,
                "OUTBOUND_PROXY": null,
                "DETECT_LINE_NUMBER": "N",
                "LINE_DETECT_HEADER_ORDER": "diversion;to",
                "REGISTRATION_STATUS_CODE": null,
                "REGISTRATION_ERROR_MESSAGE": null,
                "TITLE": "Office PBX 1"
            },
            "time": {
                "start": 1773654928,
                "finish": 1773654928.708338,
                "duration": 0.7083380222320557,
                "processing": 0,
                "date_start": "2026-03-16T12:55:28+02:00",
                "date_finish": "2026-03-16T12:55:28+02:00",
                "operating_reset_at": 1773655528,
                "operating": 0.24362492561340332
            }
        }
        

Returned Data

Name
type

Description

result
object

Object with the created SIP line

ID
string

Internal identifier of the SIP line record

TYPE
string

Type of PBX

CONFIG_ID
string

Identifier of the SIP line configuration

REG_ID
integer

Identifier of the SIP registration.

Returned when creating a cloud PBX

TITLE
string

Name of the connection

SERVER
string

Address of the SIP registration server

LOGIN
string

Login for connecting to the server

PASSWORD
string

Password for connecting to the server

AUTH_USER
string

User for SIP authorization

OUTBOUND_PROXY
string

Address of the SIP proxy for outgoing connection to the operator or PBX

DETECT_LINE_NUMBER
string

Indicator for line number detection.

Possible values:

  • Y — line number detection enabled
  • N — line number detection disabled

LINE_DETECT_HEADER_ORDER
string

Order of headers for line number detection

REGISTRATION_STATUS_CODE
integer

Status code of the SIP line registration

REGISTRATION_ERROR_MESSAGE
string

Text of the SIP registration error

INCOMING_SERVER
string

Address of the server for incoming calls.

Returned when creating an office PBX

INCOMING_LOGIN
string

Login for incoming calls.

Returned when creating an office PBX

INCOMING_PASSWORD
string

Password for incoming calls.

Returned when creating an office PBX

time
time

Information about the request execution time

Error Handling

HTTP Status: 400, 403

{
            "error": "CHECK_FIELDS_ERROR",
            "error_description": "Server address not specified"
        }
        

Name
type

Description

error
string

String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only error_description shows the reason

error_description
string

Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Code

Description

Value

CHECK_FIELDS_ERROR

Server address not specified

Required parameter SERVER is missing

CHECK_FIELDS_ERROR

Login for connecting to the server not specified

Required parameter LOGIN is missing

CHECK_FIELDS_ERROR

Password for connecting to the server cannot exceed 100 characters

Exceeded limit for parameter PASSWORD

TITLE_EXISTS

The specified connection name is already registered in the system

A line with this name already exists

MAX_CLOUD_PBX

You cannot connect more than 10 virtual PBXs.

Exceeded limit for cloud SIP lines

ACCESS_DENIED

Access denied!

Insufficient permissions to create a SIP line

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status

Code
Error Message

Description

500

INTERNAL_SERVER_ERROR
Internal server error

An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

503

QUERY_LIMIT_EXCEEDED
Too many requests

The request intensity limit has been exceeded

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit

401

NO_AUTH_FOUND
Wrong authorization data

The request contains no authorization data: neither an access token nor a webhook code was passed

401

INVALID_REQUEST
Https required

Methods are called over the HTTPS protocol only

401

OVERLOAD_LIMIT
REST API is blocked due to overload

The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support

401

ACCESS_DENIED
REST is available only on commercial plans

The REST API is available only on commercial plans. A webhook receives a different error message — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

No active webhook with the specified user identifier and secret code was found

404

ERROR_METHOD_NOT_FOUND
Method not found!

No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with provided by the access token

401

expired_token
The access token provided has expired

The access token has expired

401

user_access_error
The user does not have access to the application

The application is installed, but the Bitrix24 administrator has granted access to it only to specific users

403

PORTAL_DELETED
Portal was deleted

The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning