CallGate

HTTPS gateway for Bitrix24

by: NewSite. Support: w@newsite.by

Setup

  1. Install CallGate onto your Bitrix24 from Marketplace
  2. Go to login page and complete authorization process.
  3. Now you get your unique ukey code - use it for API calls.
  4. Use /rest/ methods listed below with ukey.

Then you can go to panel anytime by direct link and watch logs and check API status.

Be sure that you make all requests to this site via HTTPS connection - it guarantee that your ukey should not be compromated via traffic sniffers.

General

All methods must be called as HTTP GET with parameters on query. Parameter ukey is mandatory and you should pass it with every API call. Key can be acquired during login process.

Response is JSON object. Field error presented in every response and indicates state of request.

Word `entity` stands for Bitrix CRM lead, contact or company with phone number.

Data types

{PHONE} phone in short (7 digits) or international format +xxxxxxxxxx.
{NUM} digit, like -4 or 101.
{CALL_ID} unique string used as telephony call identifier.
{FLAG} if param presented in request a flag will set.
{TEXT} plain text "as is" in UTF-8 without any additional encoding.
{ENUM} one of listed values.
{..., MULTIPLE} parameter may hanlde multiple values separated by vertical bar.|

Find an assignee

/rest/find_assignee/?phone={PHONE}&telephony_show={FLAG}&internal_phone={NUM, MULTIPLE} &external_call_id={CALL_ID}&return_only_call_id={FLAG}

Params:
phone phone number to look up for assignee
telephony_show optional show CRM telephony card about incoming call
internal_phone optional internal phones of managers for receiving notifications about call
external_call_id optional additional unique string that may be used as alternative call_id identifier in following REST methods
return_only_call_id optional if set then method returns only BX.CALL_ID value as plaintext

Business logic

Lookup for existing entites with passed phone and return internal phone or entity assignee. If no lead or assignee - returns [], if assignee don't have internal phone: error = no_internal_numbers.

Example:

GET /rest/find_assignee/?phone=5551155

{"internal_number":"200","error":0}
GET /rest/find_assignee/?phone=5551155&internal_phone=202&telephony_show=y&return_only_call_id=y

externalCall.274ada6be3914aaaaaaaaaa4e4ab10f0.1000376625

Convert call to lead/action

/rest/register_call/?phone={PHONE}&direction={ENUM incoming|outgoing}&comment={TEXT}&internal_phone={NUM} &no_answer={FLAG}&no_create={FLAG}&lookup={FLAG}&no_notify={ENUM all|incoming|outging} &internal_supervisor={NUM}&tz={NUM}&http_redirect={FLAG} &telephony_show={FLAG}&call_id={CALL_ID}

Params:
phone phone in international format +xxx xx xxx xx xx. Spaces and symbols except digits and leading '+' will be trimmed
direction call direction: incoming or outgoing
comment optional comment for lead/action
internal_phone optional phone number of connected peer. If CRM user with this phone found it will be set as call assignee and receive notification.
internal_phone_answered optional like the internal_phone param, but used in cases when several phones listed – to detect primary one.
no_answer optional flag for indicate unsuccessful state of call
no_create optional flag to enable fallback logic if no phone found and new lead shouldn't be created. Will send notification to current user/assignee and internal_supervisor if present.
lookup optional indicate to perform only lookup without any notifications/actions. Useful for checking phone existency.
no_notify optional suppress notifications about activity. Values are: all (supress all notifications); incoming (supress when direction = incoming); outging (supress when direction = outgoing).
internal_supervisor optional phone number of internal supervisor/department chief. In case of flag no_create a notification will be send to this user.
tz optional timezone offset in hours from GMT+0. By default = +3
http_redirect optional if set perform HTTP 302 redirect to origin of item instead of API response.
telephony_show optional display callee card in Bitrix24 telephony subsystem. All calls except lookups registers by default.
call_id optional pass already registered call_id from Bitrix24 telephony subsystem or alternative external_call_id

Business logic

Register call as new lead or as action to existing entity.

  1. First makes lookup for leads with this phone. If no leads found then create a new one.
  2. If found several unconverted leads it makes activity for each.
  3. If all leads are converted then look up for contact with same phone.
  4. If contact found - create activity. Othervise: look up for company and do the same.

Each activity creation triggers im.notify method with message and direct link to parent entity (lead/contact/company). Message will send to item's assignee via Bitrix24 Notifications.
Call assignee resolution logic: by default assignee is the ukey holder. If there are only one phone number provided in internal_phone then it will be used as assignee. And in case if internal_phone_answered provided this user will be used as call assignee.
Additionaly internal supervisor can be assigned for each call by passing internal_supervisor param with supervisor's phone. In case of any bads (like misformated phone number or no_create case) supervisor receive a message with action description and assignee account info.

More detailed explanation:

  1. Phone number converted into international format +xxxxxxxxx (plus sign and only digits)
  2. Looking for a contact with phone number
  3. If contact found – create activity. EXIT
  4. If no contact - looking by raw phone number (as come from the request)
  5. If found – create activity. EXIT
  6. Otherwise:
    1. Looking for a company with phone
    2. If company found – create activity. EXIT
    3. If no company - looking by raw phone number
    4. If found – create activity. EXIT
    5. Otherwise:
      1. Looking up for existing leads
      2. If no leads found - looking up with raw phone number
      3. If still no leads:
        • create new lead. EXIT
        • or send notification to user if no_create flag set
      4. If some leads found on previous step:
        1. Looking for unconverted leads
        2. If some unconverted found - an activity will be created to each unconverted lead. EXIT
        3. If all leads are converted:

          Seems like your sales process broken (converted leads without targets). EXIT

Examples

GET /rest/register_call/?phone=+375175555555&direction=incoming

{error: 0, target: lead, action: new, id: 13, call_id: 'externalCall.f2000004301bb2f212f4c1f313fed000'}

GET /rest/register_call/?phone=+375175555555&direction=outgoing&comment=Recalling after meeting&internal_phone=105&call_id=externalCall.f3ff214002

{error: 0, target: lead, action: update, id: 13, call_id: 'externalCall.f3ff214002'}

Hide telephony card

/rest/telephony_hide/?call_id={CALL_ID}&internal_phone={NUM, MULTIPLE}&internal_phone_answered={NUM}

Params:
call_id Bitrix24.Telephony call identifier or alternative external_call_id.
internal_phone optional internal numbers to hide the call card
internal_phone_answered optional internal phone of user which card should be kept.

Business logic

Hides the telephony call popup card for provided call id. If internal_phone_answered set then card instances hides except the instance on answered user.

Example:

GET /rest/telephony_hide/?call_id=externalCall.274ada6be3914aaaaaaaaaa4e4ab10f0.1000376625&internal_phone_answered=204

true
// or if nothing to hide:
false

Finish telephony call

/rest/telephony_finish/?call_id={CALL_ID}&internal_phone_answered={NUM}&duration={NUM}&record_url={TEXT}

Params:
call_id Bitrix24.Telephony call identifier or alternative external_call_id.
internal_phone_answered Internal phone of user who processed call.
duration optional Call duration in seconds.
record_url optional Link to call voice recording in mp3 or wav format. Should be passed as url-encoded string.

Business logic

Finish telephony call and add to event log. If duration not passed: system will calculate duration as interval between current moment and /rest/find_assignee/ invokation time for provided call_id. When no call was registered duration will set to 1 (one) second. If call already finished and record_url provided: attaching record to finished call.

Example:

GET /rest/telephony_finish/?call_id=internal_call_13&internal_phone_answered=204&duration=30&record_url=https%3A%2F%2Fuser%3Apass%40site.com%2Fsound.mp3
// record url is `encodeURIComponent('https://user:pass@site.com/sound.mp3')`

{... call details or error message}

Redirect call to Asterisk

/rest/telephony_predial/&internal_phone={NUM}&sip_context={TEXT}

Params:
internal_phone optional Internal phone to trigger if no USER_ID came from POST request
sip_context optional Ring group line in AMI

Business logic

Lookup for AMI interface and initiate call on internal SIP line with phone provided in POST data[PHONE_NUMBER]. This method used to create callback for Bitrix WebHook events like ONEXTERNALCALLSTART and ONEXTERNALCALLBACKSTART

Example (using cURL):

Predial phone on internal phone of user 2

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'data[PHONE_NUMBER]=555-55-55&data[USER_ID]=2' \
'https://call2lead.pro/rest/telephony_predial/'

Direct Bitrix24 API calls

There are ability to use C2L as Bitrix24 API gateway without additional development.

Detailed Bitrix24 REST API documentation may be found there:https://dev.1c-bitrix.ru/rest_help/index.php

POST /rest/bitrix_api/?ukey={TEXT}&method={TEXT}

Params:
ukey ukey for an accound granted to access
method Bitrix24 API method name
POST payload optional provide a method parameters as string-encoded JSON object

Direct API output will be returned without any postprocessing. Usually Bitrix24 returns a JSON-like replies, but some methods have non-standard replies. Be aware to check response before processing.

Example (using cURL):

Get current account details withuser.current

curl -X POST 'https://call2lead.pro/rest/bitrix_api/?ukey=...&method=user.current'

Response
{"ID": "13", "ACTIVE": true, "EMAIL": "fm@rock.stars", "NAME": "Freddie", ...}

Find lead by phone withcrm.lead.list

curl -X POST -H 'Content-Type: application/json' -d '{"filter":{"PHONE": "555-55-55"}}' \
'https://call2lead.pro/rest/bitrix_api/?ukey=...&method=crm.lead.list'

Response:
[{"ID": "101", ...}, ...]

Bitrix24 Quirks

Telephony card not showing in web UI if user have active session on desktop Bitrix24 client.
Telephony card can not be hidden by API call after /rest/telephony_finish/ invoked.

Common errors

bad_ukey ukey not passed or invalid
invalid_grant if servise not used more that 30 days Bitrix24 API integration expires; user should relogin in system

© 2015-2018 NewSite LLC