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

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

Calls in CRM

Registration of inbound and outbound external calls in Bitrix24 CRM, displaying the call card to the operator, finishing with a status and duration, attaching a text transcription of the conversation.

Bitrix24 API: telephony.externalcall.*, telephony.call.attachTranscription Scope: telephony

Register a call

POST /v1/calls/register

Registers an inbound or outbound call in Bitrix24 CRM. With crmCreate: true, it creates a lead if the phone number is not found among existing entities. Returns callId for all subsequent call operations.

Request fields (body)

Parameter Type Required Default Description
ParameteruserId Typenumber Requiredyes Default— DescriptionID of the Bitrix24 user receiving the call. A positive integer. A numeric string such as "42" is also accepted. Employees
ParameterphoneNumber Typestring Requiredyes Default— DescriptionCaller's phone number in international format. A non-empty string or a number. Surrounding whitespace is trimmed. A whitespace-only string counts as empty
Parametertype Typenumber Requiredyes Default— DescriptionDirection: 1 — outbound, 2 — inbound, 3 — inbound with redirection, 4 — callback, 5 — informational
ParameterlineNumber Typestring Requiredno Default— DescriptionExternal line number of the application. List of lines
ParametercrmCreate Typeboolean Requiredno Defaultfalse Descriptiontrue — create a lead if the number is not found in CRM

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/register \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "phoneNumber": "+12025550123",
    "type": 2,
    "crmCreate": true
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/register \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "phoneNumber": "+12025550124",
    "type": 2,
    "crmCreate": true
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calls/register', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    phoneNumber: '+12025550125',
    type: 2,
    crmCreate: true,
  }),
})

const { success, data } = await res.json()
const callId = data.callId

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calls/register', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    phoneNumber: '+12025550126',
    type: 2,
    crmCreate: true,
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe registered call and its CRM link
Fielddata.callId Typestring DescriptionCall identifier for all subsequent operations
Fielddata.crmCreatedLead Typenumber | null DescriptionID of the created lead. null if no lead was created
Fielddata.crmCreatedEntities Typearray DescriptionArray of created CRM entities [{entityType, entityId}]
Fielddata.crmEntityType Typestring DescriptionType of the linked CRM entity: LEAD, CONTACT, COMPANY or an empty string
Fielddata.crmEntityId Typenumber | null DescriptionID of the linked CRM entity. null if no entity is linked

Response example

HTTP 201 — the call is registered and a new lead is created:

JSON 
{
  "success": true,
  "data": {
    "callId": "externalCall.00b1e735843c558431be668e3687a58b.1777974304",
    "crmCreatedLead": 1001069,
    "crmCreatedEntities": [{"entityType": "LEAD", "entityId": 1001069}],
    "crmEntityType": "LEAD",
    "crmEntityId": 1001069
  }
}

Error response example

400 — required parameters are missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: userId (positive integer), phoneNumber (non-empty string)"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionuserId is missing or is not recognized as a positive integer, or phoneNumber is missing or is not recognized as a non-empty string or number
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is inactive or revoked
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the telephony scope
HTTP422 CodeBITRIX_ERROR Descriptiontype is missing or its value is outside the 1–5 range — error.message contains Unknown TYPE
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error (text in error.message)
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

Search for an existing CRM entity when crmCreate: true. Bitrix24 first looks for a lead, contact, or company with a matching phone number. On a match, crmEntityId points to the existing entity and crmCreatedLead stays null. A new lead is created only if there are no matches.

The crm* fields are empty when crmCreate: false. A CRM link can be created automatically when the call is finished via POST /v1/calls/:callId/finish if Bitrix24 finds a matching number at that point.

callId is a required parameter for all subsequent steps. Save it right away: the show, hide, finish, and transcription operations all take callId in the request path.

See also