telephony.externalcall.register

What telephony.externalcall.register does

The entry point for integrating any PBX or cloud telephony that lacks a native Bitrix24 app. The register → finish → attachrecord triplet produces full CRM telephony: popups, call history on records, missed-call handling, and call statistics.

Business use cases

• Integrating a local PBX or CPaaS with no marketplace app
• Call-center platforms pushing call lifecycle into CRM
• Missed-call-to-lead automation
• Attaching recordings to CRM call history for coaching and disputes

Typical fields and parameters

• USER_ID / USER_PHONE_INNER — Which agent the call belongs to
• PHONE_NUMBER — The external party's number — normalize before sending; it drives CRM matching
• TYPE — 1 = outbound, 2 = inbound, 3 = inbound with redirect, 4 = callback
• CRM_CREATE — 1 to auto-create a lead when no CRM match exists — the missed-call-lead mechanism
• SHOW — 1 to pop the call card on the agent's screen
• CALL_START_DATE — Actual start time for accurate statistics

Example workflow

1. PBX signals inbound ring for agent 7 from +9715…
2. Middleware calls register with SHOW=1, CRM_CREATE=1 → agent sees the caller's lead card pop
3. Call ends; PBX posts duration and disposition
4. telephony.externalcall.finish with CALL_ID, duration, and status code
5. Recording ready → telephony.externalcall.attachrecord uploads/links it to the call

Example request

POST .../telephony.externalcall.register.json

{
  "USER_ID": 7,
  "PHONE_NUMBER": "+971501234567",
  "TYPE": 2,
  "CALL_START_DATE": "2026-07-07T15:40:00+04:00",
  "CRM_CREATE": 1,
  "SHOW": 1
}

Example response

{
  "result": {
    "CALL_ID": "externalCall.9a1f...",
    "CRM_CREATED_LEAD": 20641,
    "CRM_ENTITY_TYPE": "LEAD",
    "CRM_ENTITY_ID": 20641,
    "LEAD_CREATION_ERROR": null
  },
  "time": { ... }
}

Field mapping notes

• Always call finish, even for missed/failed calls — unfinished registrations leave ghost call cards and corrupt statistics; missed calls are finish with a no-answer code
• Normalize numbers to one format end-to-end; '+9715…' vs '009715…' vs '05…' produce mismatched CRM entities
• CRM_CREATE=1 on inbound is the cleanest missed-call-to-lead implementation — pair with an automation that tasks the callback

Security notes

• Recordings are sensitive: attach them into Bitrix24 rather than linking public URLs on your PBX, and control who can play them via roles

Common errors

• No call card popping — SHOW not set, wrong USER_ID mapping, or agent not marked available — verify user mapping between PBX extensions and Bitrix24 IDs
• Calls not appearing on the right lead — Number normalization mismatch between register and the stored CRM value
• Statistics show zero-duration calls — finish never sent or sent without duration — audit your PBX event handling for missed hangup events

Production implementation tips

• Build the extension↔user mapping as configuration with an admin UI, not code — agents change desks
• Queue PBX events; telephony bursts at peak hours exactly when you can least afford drops
• Log every register/finish pair; unmatched pairs are your integration health metric

Webhook or OAuth app?

Telephony middleware is long-lived infrastructure — an OAuth app with telephony scope is the right shape; webhook acceptable for single-office internal setups.

Full decision guide: webhook vs OAuth app in Bitrix24.

When to use a queue worker

PBX event streams are bursty and order-sensitive — queue with per-call serialization (register before finish before attachrecord).

How Tech Titan can help

Tech Titan builds production Bitrix24 integrations around telephony.externalcall.register and its siblings — with authentication, field mapping, queue workers, retry logic, duplicate handling, and structured logs as standard. If this method is on your critical path, bring the requirement to a free audit call and leave with an architecture sketch.