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
userId number yes — ID of the Bitrix24 user receiving the call. A positive integer. A numeric string such as "42" is also accepted. Employees
phoneNumber string yes — Caller's phone number in international format. A non-empty string or a number. Surrounding whitespace is trimmed. A string of spaces counts as empty
type number yes — Direction: 1 — outbound, 2 — inbound, 3 — inbound with redirection, 4 — callback, 5 — informational
lineNumber string no — External line number of the application. List of lines
crmCreate boolean no false true — 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
callId string Call identifier for all subsequent operations
crmCreatedLead number | null ID of the created lead. null if no lead was created
crmCreatedEntities array Array of created CRM entities [{entityType, entityId}]
crmEntityType string Type of the linked CRM entity: LEAD, CONTACT, COMPANY or an empty string
crmEntityId number | null ID 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
400 MISSING_PARAMS userId 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
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY Invalid API key
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
401 KEY_INACTIVE The API key is inactive or revoked
403 SCOPE_DENIED The key is missing the telephony scope
422 BITRIX_ERROR type is missing or its value is outside the 1–5 range — error.message contains Unknown TYPE
422 BITRIX_ERROR Bitrix24 returned an error (text in error.message)
429 RATE_LIMITED Request limit exceeded
502 BITRIX_UNAVAILABLE Bitrix24 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.

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: all show, hide, finish, transcription operations take callId in the request path.

See also