telephony.externalcall.register

Scope: catalog Permissions to execute: for all

Method registers a call in Bitrix24. For this purpose, it searches an object that corresponds to the number in CRM. If the method finds it, it adds the call, connected to the object found. If the method didn't find it, it can create a lead automatically.

First user previously responsible for this customer is assigned as the responsible for a new lead automatically when using telephony.externalCall.register. You subsequently can change such responsible user via telephony.externalcall.finish.

Simultaneously with the registration of a call, method optionally can show the user the call ID screen. The user that views the displayed call pane, is identified either by USER_ID or by USER_PHONE_INNER. (That is, fields are marked as required, but actually, only one of two is required).

No need to repeatedly call this method for call received at the event OnExternalCallStart. Such calls have been registered already in the system and you need to only call telephony.externalcall.finish when call finishes.

Attention! Repeated call telephony.externalcall.register with the same parameters, without closing the previous call by the method telephony.externalcall.finish - fetches the same CALL_ID during 30 minutes.

To create a call "activity", it is also necessary to call the telephony.externalcall.finish method

Returned value

Method returns an array:

Parameter	Description	Type of value
CALL_ID	Call ID inside Bitrix24.	int
CRM_CREATED_LEAD	Created lead ID (is created, if the object is not found in CRM by the incoming number)	int
CRM_ENTITY_ID	ID of the object found in CRM.	int
CRM_ENTITY_TYPE	Type of the object found in CRM by the incoming number CONTACT \| COMPANY \| LEAD.	string
CRM_CREATED_ENTITIES	Array with entities automatically created in CRM when registering a call. Format: ENTITY_TYPE - created entity type ENTITY_ID - created entity ID	array
LEAD_CREATION_ERROR	Error text, occurring when creating a lead in CRM.	string

Function parameters

Important! This parameter value are used in Bitrix24 Sales Intelligence scenarios. That's why the solutions with telephony integrations for Bitrix24 applications catalog strictly required to pass a phone number here, which received a registered inbound call.

Parameter	Description	Type of value
USER_PHONE_INNER	Internal number of the user. Required.	string
USER_ID	User ID. Required.	int
PHONE_NUMBER	Telephone number. Required	string
CALL_START_DATE	Date/time of the call in the ISO8601 format. Please note, that the date must pass an hour zone, to avoid confusing call time. Example: `2021-02-03T18:25:10+03:00 .`	string
CRM_CREATE	[0/1] Automatic creating of CRM entity associated with a call. If required, creates a lead or deal in CRM, depending on settings and performance CRM mode There: - simple CRM mode (without leads) - creates a deal instead of a lead; - repeated sales mode with created deal/lead even if there's a existing CRM entity found (However, doesn't create such entities, if there's an existing active deal/lead or a number has been blacklisted in CRM). . Please note, a deal activity is created with any value of this parameter, if possible.	int
CRM_SOURCE	STATUS_ID of the source from the source selection list. You can receive a list of sources by the crm.status.list method with filter by `"ENTITY_ID": "SOURCE"`.	string
CRM_ENTITY_TYPE	Type of CRM object, from the details card of which the call is made - CONTACT \| COMPANY \| LEAD.	string
CRM_ENTITY_ID	CRM object ID, type of which is specified in CRM_ENTITY_TYPE	int
SHOW	[0/1] Option to display or not the call ID screen (by default is 1).	int
CALL_LIST_ID	Call dialing list ID, to which the call should be connected.	int
LINE_NUMBER	Number of external line, via which the call was made (see. telephony.externalLine.add). Optional.
string
TYPE	Type of call: 1 - outbound 2 - inbound 3 - inbound with forwarding 4 - callback	integer